Migrate static site away from Gatsby.

[andrico1234]

Research: Migrate static site away from Gatsby

This is a proof-of-concept to understand the complexities of moving our Open UI site away from Gatsby, to something more simple, like 11ty or SvelteKit.

Why do we want to do migrate away from React/Gatsby?

For the most part, the Open UI site is a data-driven and static site.

For almost every page, we render static content using MDX or JSON data, yet we're requiring contributors to understand React and Gatsby to easily make changes to the Open UI site.

While Gatsby's purpose is to develop blazing-fast websites, it requires knowledge of:

• React
• GraphQL
• Gatsby's own build system (gatsby-browser, gatsby-config, gatsby-node)

This adds a huge level of friction for those who want to contribute to Open UI. This isn't conducive for a community where anyone can easily contribute, not just React developers.

We want to reduce as much friction for people to contribute to the repo, by bringing the tech stack down to the lowest level needed. Ideally, down to little more than HTML, CSS, and JavaScript

Also, on several occassions, various members of the Open UI community have had problems with installing Gatsby, due to the notoriously fickle Sharp module.

The results of such a migration will ensure that the Open UI site is:

• Easier to contribute to
• Easier to maintain
• Future proof (React knowledge no-longer required, just some HTML, CSS, and a little JavaScript)

The aim of this proof-of-concept is to validate whether migrating to a tool like 11ty leads to the above effects.

I'm currently exploring this in the spike/11ty-exploration branch if anyone's interested in seeing this PoC in action.

Option 1: 11ty

I've begun exploring 11ty, which gives us flexibility in how we write our HTML templates and define our data. There are a handful

Option 2: ...

Suggest your own,

though I've considered tools like Rocket and Sveltekit as possible options.

Todo

Settle on a templating engine

11ty lets us choose from a handful of templating engines out of the box, such as Markdown, Nunjucks, EJS, and vanilla JS.

MDX is notably omitted, which is the template language we use for the majority of our static content in the existing site. We could look to use an MDX plugin for 11ty, but there look to be significant tradeoffs with doing so.

Prove migrating styles

In the current site, Open UI uses several methods for managing styles:

• inline styles
• styles in .css files
• defining a styles via Typography.js

Components like the Header component have their own inline styles

There are also a handful of additional *.css files:

global.css, table-anatomy.css, spec.css, and anatomy.css.

Gatsby uses the Typography.js plugin to generate our styles at build-time and is then served as a static .css file.

Migrating styles

Using a standard .css solution may be simple enough for a such a site. To simplify the migration of the typography.js styles, we can leverage its toString() API which allows us to write out a css file at build time.

Typography offers an API that lets us convert the design object to a CSS output. We can invoke this function when our build starts to automatically generate our css file. Eleventy then handles the rest.

Prove migration of interactive elements

Instead of using React to manage complex UI, we can leverage web components instead.

One example of how to do this can be found here, but will add complexity to our build tooling.

Template engines like Nunjucks will allow us to reuse layouts, via frontmatters layout key, while we can use macros to reuse component logic.

While I'm still in the exploration phase with Nunjucks, the approach of using macros to reuse components doesn't feel as intuitive as writing JSZ, and passing through props. If this issue persists, it goes against one of the principles of this rewrite, to make the repo easier to contribute to.

Other possible avenues could be to:

• simplify some of our more complex components, such as the concepts collapsible.
• leverage an MDX plugin, and pay for the tradeoffs
• use web components (lit?) for more complex components.

Migration plan

Proof of concept

• [x] Install Eleventy
• [ ] Settle on a template engine (Nunjucks, Lit?)
• [x] Prove migrating styles
• [ ] Prove converting MDX to 11ty
• [ ] Prove serving images
• [ ] Prove site navigation
• [ ] Prove migration of interactive elements (web components?)

Pre-merge

• [ ] Migrate all existing pages to 11ty
• [ ] Migrate styles
• [ ] Migrate images
• [ ] Port over the component name matrix
• [ ] Add 404 page
• [ ] Ensure site metadata (HTML head) is consistent
• [ ] Add Readme detailing installation and contributing steps
• [ ] Match manifest file from Gatsby site
• [ ] Regression test the entire app
• [ ] Handle redirects (e.g. contribute.js)
• [ ] A11y and usability review

Post-merge

• [ ] Deploy to Netlify
• [ ] Remove platform directory + bring research to the top level
• [ ] Consolidate styles into a single format.
• [ ] Ask Zach nicely to add the Open UI site to the 11ty leaderboard 🥺

[daKmoR]

Rockets goal is to be as close as possible to web standards... for example no dedicated template engine... using tagged template literals in html, markdown and js. Components are web components. Fully ESM.

I guess that would be a nice fit 💪

there are also major improvements happening right now 🎉 including SSR of web components 😱

https://twitter.com/daKmoR/status/1506601983293235209?s=20&t=SQN4cq-AV7mMi91aY11c-g

WIP website https://next.rocket.modern-web.dev/

[andrico1234]

Thanks @daKmoR for commenting,

I've been playing with Rocket as an option since initially posting this issue. 😄 I haven't gotten too far with it, but having an mdjs file format was one of the biggest draws!

[andrico1234]

Catch up 12/08/22

Agenda

• Review our learnings from the research phase
• Propose a solution
  • To Jon, why are you moving away from 11ty?
• Are there still any unanswered questions that we need to answer before we move along with a choice?
  • Are we happy to move ahead with Astro?
  • Are there any risks we need to mitigate?
  • Are there any other options we can take to resolve the problem?

Open Questions (for future)

• How do we want to write our components going forward? Are we happy going with .astro components (a newer template format), instead of .jsx for the performance benefits? Not a question we need to answer yet, as our phase 1 is to offer an equivalent experience, which means move over to .jsx.

Notes

• Both have had positive experiences with Astro. Migrating to both .astro and Lit components
• As we move toward phase 2, we should discuss with contributors which templating language they’d most prefer to write in.
• We’ve tried migrating existing pages, jsx components, icons, markdown content, images, etc, and everything works.
• Astro’s plugin ecosystem is getting better. No image package when we started, but now there is.
• Considered 11ty, but the migration path from Gatsby → 11ty is much more challenging than Gatsby → Astro.
• Both Vic and I are happy to move ahead with Astro.

[github-actions[bot]]

There hasn't been any discussion on this issue for a while, so we're marking it as stale. If you choose to kick off the discussion again, we'll remove the 'stale' label.

[lukewarlow]

The site now uses astro