gatsby
gatsby copied to clipboard
docs(gatsby-source-filesystem): add warning about `parentNodeId` for util functions like `createFileNodeFromBuffer`
Description
We wanted to implement a social card that is generated on the fly for our pages. createFileNodeFromBuffer
was our obvious choice. We followed the playbook given by Gatsby, here the relevant docs:
-
gatsby-source-filesystem where the helper functions
createRemoteFileNode
&createFileNodeFromBuffer
are defined. - Nodes with foreign key relationships
Steps:
- Create the file node with
createFileNodeFromBuffer
- Write the file node id to given node with
createNodeField
- Resolve the fk relationship through
createSchemaCustomization
&@link
Everything worked, but only on the first start. Repeated starts showed the file being null. Clearly something was going on when loaded from cache. We studied the documentation and searched for examples on github through the code search. We didn't found obvious solutions only a few issues describing similar issues in other contexts.
When I compared the two function's parameter signature I noted a small difference that technically did not make a difference but semantically. Inside createFileNodeFromBuffer
parentNodeId
receives a default value of null
and that value is not mentioned in the documentation.
On the other hand the documentation for createRemoteFileNode mentions that value and the source code shows now default null
assignment for parentNodeId
.
When I thought about the cache and dangling file nodes I guessed this is the problem and in the end this was exactly the issue. @KyleAMathews himself created an issue (https://github.com/gatsbyjs/gatsby/issues/11942) almost 3 years ago to handle this problem but it was closed by the stale bot and forgotten I guess? The related PR which introduced the parentNodeId
and where Kyle commented the problem can be found here https://github.com/gatsbyjs/gatsby/pull/11795#issuecomment-465760274.
Documentation
This PR brings the necessary changes in the documentation and I chose to print a warning for createFileNodeFromBuffer
& createRemoteFileNode
which reads like this for createFileNodeFromBuffer
:
It seems that you forgot to pass in 'parentNodeId' for a file you try to create with 'createFileNodeFromBuffer'. Not doing this is causing problems as a) when the server is restarted, if the parent of the created file node is loaded from the cache, the linked file node won't be recreated which means it will be garbage collected and b) if a parent node is deleted, the linked file node won't also be deleted.
The documentation was adapted for the following parts:
-
createFileNodeFromBuffer (link to current version) gets a new paragraph to warn about the
parentNodeId
issues. - The same warning for createRemoteFileNode (link to current version)
- Added a new troubleshooting aspect at the bottom of the page.
- i changed the example for
createFileNodeFromBuffer
. Right now it's some outdated example picked from https://github.com/malcolm-kee/gatsby-source-mysql. It's outdated, because it's not using theparentNodeId
while the current sources do use them and switched tocreateRemoteFileNode
anyway in the meantime. I chose to extract the important bits from our working social image generation which is a much more simpler example that might be relevant to other folks in addition.
Note: I copied and adapted large positions from Kyle's feedback to this issue but I had no idea to give proper credit, so I'm doing it here instead. Thanks.
Remarks
I actually would like to make parentNodeId
a mandatory field and throw an exception like it's done for other inputs. That would be a breaking change I fear so I chose to only warn about the issue. Does some maintainer have an opinion on this?
Preview
The rendered documentation files change in those aspects. Red highlights only to highlight the screenshots.
Warning for createFileNodeFromBuffer
Warning for createRemoteFileNode
Updated Example
Troubleshooting Addition
Related Issues
- https://github.com/gatsbyjs/gatsby/issues/11942
- https://github.com/gatsbyjs/gatsby/pull/11795#issuecomment-465760274
- https://github.com/MantasMikal/gatsby-source-instagram-all/pull/5
- https://github.com/oorestisime/gatsby-source-dropbox/pull/9