Details on how createPagesStatefully works

[pierluigizagaria]

There are no clear info on how createPagesStatefully works in the docs. I thought that the difference from createPages was that the pages does not get GC between runs even without rebuilding pages. But this is not the case. I don't know if this is a bug or something.
Does anyeone used this api with success or difference from createPage? Thank you

[ranjanashwin]

You're right — the docs don’t go into much detail about createPagesStatefully, and it can be a bit confusing.

To clarify: the main purpose of createPagesStatefully is to opt out of automatic page garbage collection during incremental builds. In contrast, createPages will cause Gatsby to automatically remove any pages that weren’t recreated in a subsequent run.

If you're using createPagesStatefully, Gatsby assumes that you're managing the full lifecycle of those pages and won't delete them automatically between builds — which is useful for cases like:

• Persisting dynamically created pages that aren’t easily re-generated
• Managing a large external data source where deletions need manual control

However, this only applies in develop mode or incremental builds. If you run a clean build (gatsby clean && gatsby build), all pages are recreated regardless of which API was used.

If you're not seeing this behavior, it might be worth checking whether any plugins or cache behavior is interfering.

Let me know if you’re using a specific data source or plugin — happy to help dig in further.