Meta: Replace the current Infrastructure with Next.js

[ovflowd]

This is a Meta issue regarding the current Website Redesign Initiative that has taken place on the https://github.com/nodejs/nodejs.dev repository since 2019.

We believe that in terms of features, design and content the https://nodejs.dev website reached its goals and pretty much has the format we all desired. (Or to a certain extent).

The overall idea is to incrementally move the feature-set from the new website to the current website. The overall idea is explained here and it would, in summary, mean that the underlying infrastructure of the website would be dropped to support Next.js. But what does that mean exactly?

• The current written from scratch Framework would be dropped to adopt Next.js
• Next.js would need to support the exact current process of building this website on our current Website Infrastructure (With maybe a few modifications to be checked with the Node.js Build WG)
• All the current content and layout would be the same with the exception of:
  • The file-directory structure would change in order to accommodate Next.js
  • Some files might become redundant or be removed
  • Some files might be renamed to accommodate Next.js's i18n feature-set
  • The same configuration files will be preserved, e.g.: How we do Banners
  • The pure HTML templates would switch to over JSX/React

After that, the next steps would be (not necessarily in this order):

• Adopt the SCSS/CSS Modules styling from Nodejs.dev and incrementally adopt the design, by also porting the CSS over, the components and pages (Starting from the Home Page, then going to the next and next one)
  • The plugins/modules necessary such as MDX, i18n and others would be port over the time
• The remaining extra pages, sections, content and base functionalities such as i18n and dark mode would be ported over.
• Extra features and complex sections (such as API docs) would be done at the last step, such as:
  • Search functionality
  • Proper RSS functionality
  • Offline-mode with Service Workers
  • And many others

This would be a long-term effort work, that I'm pretending to commit myself with and would love the support of the existing @nodejs/website and @nodejs/nodejs-dev teams to make this a reality.

There are plenty of benefits with this approach, and I'm definitely open for discussion and more. There's an open issue here for scheduling a bi-weekly meeting for the Website WG, and anybody interested (being part of the WG-or-not) is welcome here!

[ovflowd]

Folks at Vercel let us know about a few features that would be super useful:

• Feature Flags: https://vercel.com/blog/edge-config-ultra-low-latency-data-at-the-edge
• Collaborative Reviews: https://vercel.com/blog/using-vercel-comments-to-improve-the-next-js-13-documentation

[webketje]

Did a quick perf & mem usage test (using Firefox devtools) on nodejs.org/en/download & nodejs.dev/en/download (because those are popular pages & support more or less the same functionality)

	nodejs.org/en/download	nodejs.dev/en/download
Memory usage	~4.7MB	~22.1MB
Network data transfer size	~0.2MB	~4.9MB
Network data latency	0.5s	2s

Disclaimer: as the maintainer of metalsmith, I'm sad to see its most flagship website move away from it (especially since it's been improving fast since 2022 and I've been in contact with current maintainers regarding certain plugins). The nodejs.dev site does add some overhead in memory usage (x5) and increases the amount of data requested (x25), and note for a documentation page this also holds (11MB nodejs.org/docs -> 60MB nodejs.dev/docs).

I personally don't like the opinionated blend-all-concerns, one-tool-fits-all approaches of modern webtools like Next.js (or Gatsby, or Nuxt.js). Metalsmith might require you to put in some more effort for certain features, but you will never be "stuck" because of it. Any Node.js developer with basic JS & markdown knowledge can understand the build in the glimpse of an eye without having to write everything in JS and learn JSX, or browse through tons of fast-evolving docs. Then again, I might be the odd one out because I also couldn't care less about a "light/dark" theme switch. That said, IMO the new features and updated design of nodejs.dev may justify the (slight, depending on internet connection & device RAM) perf/ network latency penalty.

[ovflowd]

@webketje just a quick reminder that:

• nodejs.dev is not made in next.js but gatsby
• nodejs.dev and nodejs.org live in different infrastructures with different bandwidth and resources (nodejs.dev lives on a free G Cloud server)
• nodejs.dev has way more assets and javascript codebase naturally increasing the memory and resource usage

[ovflowd]

I'd also like to comment that this approach of benchmarking isn't really appropriate as there are way too many things at play here (such as extra network requests, service workers, et cetera), nevertheless Gatsby adds a lot of overhead on top that definitely are non-optimal, and possibly some of the causes of the extra overhead.

[ovflowd]

Finally, I'd like to appreciate your work with metalsmith and for supporting us during all this time. Your work is not going to waste 🫶

I do understand and respect your own opinions and preferences and I also believe that for the feature set we need we must depart from the current infra.

Regardless, I don't want to sound like I'm just being picky on your benchmark, data is data, and indeed things are relatively hungrier now 👀 gonna def prioritise slimming down those fat docs ♻️

[webketje]

We're on the same page, all points taken. The quick perf/mem test was just to satisfy superficial curiosity, and the second part is just an opinion/ preference. I got practically attached to this repo as I use it to sanity-check new releases work locally.

I give you a 👍 here because not sure how to do it on a comment in Github's mobile PWA

[nschonni]

• nodejs.dev and nodejs.org live in different infrastructures with different bandwidth and resources (nodejs.dev lives on a free G Cloud server)

PS: Minor, but I don't think that it's on a free tier for the .dev, but some credits from @MylesBorins from the regular Google cloud offering

[nschonni]

Copied from https://github.com/nodejs/nodejs.org/pull/4991#issuecomment-1404050864

• Might be work creating a snapshot of the old website and host it at old.nodejs.org with a warning banner. Could probably restore some of the other content like the deleted Knowlegebase articles that had a few issues opened about
• I think the Learn stuff done over on .dev is nice, but I think keeping that site/repo around for that content to live separately might make sense.
• Before pulling the docs content into this repo, it might be worth looking at leveraging https://github.com/nodejs/i18n as a spot to create a new docs.nodejs.org

[ovflowd]

Might be work creating a snapshot of the old website and host it at old.nodejs.org with a warning banner. Could probably restore some of the other content like the deleted Knowlegebase articles that had a few issues opened about

That makes sense. It would be good even for posterity reasons :) (cc @Trott wdyt?)

I think the Learn stuff done over on .dev is nice, but keeping that site/repo around for that content to live separately might make sense.

It would make sense if both websites planned to be different, but the idea is that nodejs.org will have the exact same layout, pages (content), and feature set from nodejs.dev, and eventually, nodejs.dev will sunset. (The only difference is that all the blog posts from nodejs.org will be kept).

Before pulling the docs content into this repo, it might be worth looking at leveraging nodejs/i18n as a spot to create a new docs.nodejs.org

We don't have plans to bring the newly designed API docs from nodejs.dev to this repository yet, the reason being there are too many open topics, such as:

• /api/ is a route managed by nginx and points to somewhere else on nodejs.org
• Currently, nodejs.dev only serves the active maintained or on active maintenance mode API versions... We need to figure out the redirect/URL schema for all the other API versions not generated by the website. [It could even be an nginx rule or a Next.js middleware route (if we use Vercel infra or Next.js CLI) to redirect to an archive for the older docs]
• We currently have the new API metadata proposal that has some pending work to create new tooling for the API docs.

[ovflowd]

BTW @nschonni thanks for putting these together :)

[nschonni]

I not fully fleshed out idea for the old, would be to fork/copy to https://github.com/nodejs/old.nodejs.org and use GitHub pages for a basic way. nginx redirects wouldn't work, and I'm not sure if there would be issues getting the CNAME to point it, certs, etc...

[ovflowd]

Closing as we adopted Next.js and this is done.