Migrating from Gatsby: Astro, Next.js, Waku…?

[SachaG]

The results apps (such as https://2025.stateofjs.com/) are currently using Gatsby.

Requirements

The requirements for the app are:

• TypeScript support
• React support
• Static site generation (generate HTML files)
• Can build/deploy many pages relatively fast

In addition, two nice-to-have more advanced features would be:

Hybrid Rendering

The ability to prerender some routes as HTML pages at build time, but also support dynamically server-side rendered routes at the same time (useful for things like dedicated metatags routes for social media sharing).

"Soft" SPA-style internal navigation

The ability to navigate the site without refreshing the page and having to reload the JavaScript bundle, while maintaining state etc. from page to page.

Gatsby ❌

This is what we currently use. There are a couple issues with the current system:

• Gatsby is not well-supported anymore, and if things break they might not get fixed.
• Very long build times
• We don't really use any of Gatsby's features.

Astro ❌

Astro is great but presents two issues:

• Loses some of its benefits if you don't use .astro components (in our case we want 100% of the components to remain in React for easier portability).
• Does not support "soft" SPA-style internal navigation (as far as I know)

Next.js ❌

Pros:

• Supports all requirements
• Already used elsewhere in the stack

Cons:

• It's Next.js (complex, heavy, etc.)…

Waku ✅

The other options I've been considering is Waku. Although it's much newer and smaller than Astro, it supports all requirements and doesn't have the baggage of Next.js.

Something else?

I'm not aware of other good options but if there are, I'd love to hear about them!

[SachaG]

Migration Roadmap

1. i18n

Before anything else, we need to make sure we can properly support multiple locales (/en-US/frameworks, /ja-JP/frameworks, etc.). We will need to load the list of locales via a GraphQL query to the API

// TODO: add GraphQL query to get all locales

2. Site Architecture

The first step should be to recreate the site's page architecture via dynamic/declarative routing based on the raw_sitemap.yml files. Note that ultimately these files will migrate to the surveys repo and need to be retrieved via the API, but we can do that later.

3. Data Loading

The next step will be taking care of data loading. We can either batch-load data at the route level for an entire page, or at the component level. Doing it at the component level is simpler from an architecture point of view, but it also means more requests and might slow down the build, but maybe that's ok since it only happens once at build time.

4. Blocks

The results app uses a system of "blocks" for each chart or content element, with corresponding templates.

5. Layout + Generic Components

We can then work on re-enabling the layouts, header, nav, etc. and all the other generic components that constitute the app.

6. Survey Themes/Configs

Each survey has its own logo, colors, fonts, etc. These are currently stored in the monorepo, so we can keep them there for now. But ultimately it would be good to also make them part of each survey's config in the surveys repo. Although I am not sure how to do that for logos, which are React components.

7. CSS Migration

The current app uses a mix of Styled-components (legacy), global SCSS files, and (S)CSS Modules. It would be good to eventually migrate everything to CSS Modules.

[arayaryoma]

@SachaG
I've already run into an issue with adopting Waku.
Waku doesn't support trailing slashes for SSR (e.g., /en-US/). Because of this, we'd need to change the locale paths to /en-US or set up a reverse proxy in front of the app server to map /en-US/ to /en-US.
Since this would break backward compatibility, it makes it difficult to adopt, don't you think?

[SachaG]

Let me ask in the Waku Discord.

[arayaryoma]

opened an issue on GitHub: wakujs/waku#1966
(I thought an issue would be better than Discord since it's a more public place)
Anyway, I found that we can use trailing-slashes by using config-based routing instead, so I'll continue investigating with that for now.

[dai-shi]

@arayaryoma Would you be able to try the current main waku to see if there's anything missing?

npm i https://pkg.pr.new/waku@6dfbc99

[arayaryoma]

@arayaryoma Would you be able to try the current main waku to see if there's anything missing?

npm i https://pkg.pr.new/waku@6dfbc99

Thank you! I'll try it soon!

[arayaryoma]

@dai-shi
I tried the sample code and it seems to work well! 👏🏻

Thanks for the quick implementation!