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) or src/shared-ui/ (EBRAINS-specific pieces such as the cookie notice).

Structure the folder

FileRequiredWhat it holds
eds-name.tsxYesThe component: props, events, methods and render
eds-name.cssIf styledIts styles. Tailwind classes and the --eds-* variables apply
eds-name.spec.tsYesUnit tests (newSpecPage)
eds-name.e2e.tsxFor interactive componentsBrowser tests
eds-name.stories.tsxYesStorybook stories: the default plus each meaningful variant
readme.mdGeneratedProps, 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 on prefix (form, edsclose). React then gets onForm and Angular (form).
  • Methods (open(), close()) are @Method() and async.
  • Defaults are the common case; options are opt-in (showLabel is false by default).
  • Don’t remove or rename a prop in a minor release: mark it @deprecated with 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

  1. Write JSDoc for the component and every prop, event and method. readme.md is generated from it on build.
  2. Add the sidebar name and a one-line description to apps/live/eds-docs/data/components.yaml.
  3. 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 components and nx test components pass