How to Develop Stencil Components
How to add or change a component in packages/components, so it works in every framework, documents itself and passes review. Start from For contributors if you haven’t proposed the change yet.
Before you start: the monorepo is set up (Configure Monorepo), and you know the basics of Stencil.
Name it
- Tag names start with
eds-and use kebab-case:eds-rating,eds-input-field. - The name says what the component is (
eds-tag), not how it looks (eds-green-pill). - One component per folder under
src/components/(general components) orsrc/shared-ui/(EBRAINS-specific pieces such as the cookie notice).
Structure the folder
| File | Required | What it holds |
|---|---|---|
eds-name.tsx | Yes | The component: props, events, methods and render |
eds-name.css | If styled | Its styles. Tailwind classes and the --eds-* variables apply |
eds-name.spec.ts | Yes | Unit tests (newSpecPage) |
eds-name.e2e.tsx | For interactive components | Browser tests |
eds-name.stories.tsx | Yes | Storybook stories: the default plus each meaningful variant |
readme.md | Generated | Props, events and methods from your JSDoc; becomes the docs page |
Build it so every framework can use it
These rules come from building the same app in React, Vue and Angular. Breaking one shows up as a bug in one framework only.
Read props when the component loads, not in field initialisers
Angular sets inputs after the element is created but before its first render. A value computed in a field initialiser misses them:
React to props that change after load
Frameworks can set or replace a prop at any time. Recompute derived state in a @Watch:
Accept objects as properties, and strings as a fallback
Arrays and objects (links, fields, data) arrive as properties from frameworks and as JSON strings from plain HTML attributes. Accept both, and make optional fields optional in the type, so TypeScript apps aren’t forced to fill them in.
Keep the API small and predictable
- Props are camelCase in code (
showLabel) and kebab-case as attributes (show-label). - Events are lower-case, without an
onprefix (form,edsclose). React then getsonFormand Angular(form). - Methods (
open(),close()) are@Method()andasync. - Defaults are the common case; options are opt-in (
showLabelisfalseby default). - Don’t remove or rename a prop in a minor release: mark it
@deprecatedwith what to use instead.
Make it accessible
Native elements first (<button>, <dialog>, <input>), visible focus, full keyboard use, and labels on everything interactive. Check against the accessibility guidance.
Send analytics for interactions
Report meaningful interactions with sendAnalytics() from src/utils/analytics.ts, as eds-button does. Never send personal data.
Keep internal pieces out of the docs
A component that only exists to build other components or the docs site gets @internal in its JSDoc. The docs site then gives it no page, route or sidebar entry:
Test and preview
Then check the component in an app, ideally the sandbox for your framework (apps/live/sandbox, react-sandbox or angular-sandbox).
Document and record it
- Write JSDoc for the component and every prop, event and method.
readme.mdis generated from it on build. - Add the sidebar name and a one-line description to
apps/live/eds-docs/data/components.yaml. - Add an entry to
packages/components/CHANGELOG.md, under Added, Changed, Fixed, Deprecated or Removed (how to keep a changelog).
Acceptance criteria
A component is ready for review when:
- It follows the naming and folder structure above
- A spec covers its props, events and edge cases, and passes
- Stories show the default and each variant, with working controls
- It works when its props are set after load (Angular, Vue) and when data arrives as properties (React)
- Keyboard use and visible focus work, and every control has a label
- Interactions send analytics
- JSDoc is complete, and it has an entry in
components.yaml(or@internal) - The changelog has an entry
-
nx lint componentsandnx test componentspass