Fred

MDN's next fr(ont)e(n)d.

Getting started

1. Copy .env-dist to .env and update
2. Install dependencies npm install
3. In one terminal window, start the backend: node --env-file=.env --run rari -- serve
4. In another terminal window, start the frontend:

• Run local dev server npm run dev
• Open http://localhost:3000/en-US/ to see the homepage

Note

If you already have another local server running on port 3000, fred will use the next available port (e.g. 3001).

Development principles

Components and Elements

• Components should live in the components/ folder, with reserved names which cause certain behavior, explained further below:
  • component-name/
    • global.css - (reserved): automatically added to global styles
    • element.js - (reserved): custom element, automatically imported client side, always imported server side
    • element.css - (recommended): styles for custom element's shadow dom
    • server.js - (reserved): server component, will automatically load the adjacent server.css file when used
    • server.css - (reserved): automatically added to page styles when its server component is used in that page
• global.css: components which have CSS which should be loaded on all pages should expose that through a global.css file:
  • This should be used sparingly, use it for things needed in almost all components, like colors, fonts, etc.
  • Or, when creating a custom element, use it to set the "browser default" styles on that custom element: usually as simple as just mdn-component-name { display: block; } or similar
• element.js: custom elements should be defined in components/component-name/element.js
  • The class should be exported, and named MDNComponentName
    • Acronyms should be kept all caps, to match the naming of HTMLElement class names, and added to ACRONYMS in build/plugins/generate-element-map.js to allow the correct types to be generated
  • The element should be registered with a name of mdn-component-name
  • If all this is done:
    • The element will be automatically loaded client side if it's present in the DOM at page load
      • Elements inserted client side (i.e. in a hook, or another custom element) won't be automatically loaded, and the hook should handle loading them: probably with an async import()
    • The element will be automatically loaded server side for SSR
    • The element will automatically be added to types/element-map.d.ts to provide proper types in e.g. querySelector("mdn-component-name")
• server.js: server components should be defined in components/component-name/server.js
  • The class should extend ServerComponent from components/server/index.js, and be named ComponentName
• server.css: server component styles should be placed in components/component-name/server.css
  • These will be automatically loaded server side when the adjacent ServerComponent is used
    • Therefore, these styles should be scoped to the component, usually with a wrapping class

Typing

• We use TypeScript in JSDoc annotations for typing, so we can write and directly execute JavaScript (with no transpilation step)
• We occasionally use TypeScript files directly for writing types/interface which are too complex to easily write in JSDoc
• Eventually we'll have a fully typed codebase, with no errors: while we're in active development we can ignore errors in the interest of development speed/pragmatism:
  • If we do so, we should use // @ts-expect-error so we get an error when we fix the error and don't leave unnecessary // @ts-ignore comments lying around. While we're in active development these can lack a comment, but eventually we'll require an explanatory comment on each.