docs(gatsby-source-filesystem): add warning about parentNodeId for util functions like createFileNodeFromBuffer

[georgiee]

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:

1. Create the file node with createFileNodeFromBuffer
2. Write the file node id to given node with createNodeField
3. 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 (#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 #11795 (comment).

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 the parentNodeId while the current sources do use them and switched to createRemoteFileNode 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

• Warn if a source/transformer plugin isn't setting parentNodeId with createRemoteFile #11942
• fix(gatsby-source-filesystem): Let plugins set parent when creating File nodes with createRemoteFileNode #11795 (comment)
• Set the parentNodeId so File nodes aren't garbage collected on restarts MantasMikal/gatsby-source-instagram-all#5
• Add parentNodeId to remote file nodes oorestisime/gatsby-source-dropbox#9

[georgiee]

Actually I would like to enforce this and throw an error, but I don't dare to suggest such a potential breaking chance. Does one of the maintainers has an opinion on that? Do we have use cases where parentNodeId is indeed allowed to be null?

[georgiee]

Same as in create-file-node-from-buffer.js:

Actually I would like to enforce this and throw an error, but I don't dare to suggest such a potential breaking chance. Does one of the maintainers has an opinion on that? Do we have use cases where parentNodeId is indeed allowed to be null?