Skip to content

feat: add x-render-dependencies for SSR/SSG metadata - #148

Open
SisyphusZheng wants to merge 2 commits into
webcomponents:mainfrom
SisyphusZheng:x-render-dependencies
Open

SisyphusZheng wants to merge 2 commits into
webcomponents:mainfrom
SisyphusZheng:x-render-dependencies

Conversation

@SisyphusZheng

@SisyphusZheng SisyphusZheng commented May 15, 2026

Copy link
Copy Markdown

Summary

Adds one experimental x-render-dependencies?: string[] field to CustomElement for direct custom element dependencies referenced by an element's own render output.

Consumers such as SSR and SSG tools can use the direct edges to resolve transitive dependencies, detect cycles, and prepare component definitions before rendering.

Closes #147.

Scope

This PR now follows the issue's intentionally narrow scope and adds only x-render-dependencies. Renderer selection, hydration capability, and shadow-root configuration are left for separate proposals.

The x- prefix is proposed as an experimental convention, following the discussion in #38; it is not presented as an already-established CEM extension mechanism. The field intentionally uses string[] without an incomplete ASCII-only tag-name regular expression.

Changes

  • Adds x-render-dependencies to the TypeScript schema.
  • Regenerates schema.json from schema.d.ts using the repository build command.
  • Adds tests that assert the field is present on custom element declarations and that a positive example is accepted.
  • Adds an Unreleased changelog entry.

Validation boundary

The generated JSON Schema describes the field as an array of strings, but this PR does not claim that every malformed value is currently rejected. #138 tracks the existing declaration-union / anyOf validation ambiguity. Fixing that issue is intentionally out of scope here.

Motivating implementation

OpenElement provides a working nested-component rendering path that motivates making direct render dependencies discoverable:

This is evidence for the metadata use case, not a claim that every SSR implementation uses the same algorithm.

Verification

npm run format
npm run build
npm test

The test suite passes 3/3, and running the schema build repeatedly produces the same schema.json.

… for SSR/SSG metadata

Add four x- prefixed fields to CustomElementDeclaration and
CustomElementMixinDeclaration schemas, plus TypeScript type definitions
and documentation.

Fields:
- x-render-dependencies: tag names that must be registered before
  this component can render (enables SSR topological sort)
- x-layer: SSR capability (server-only / server-hydratable / client-only)
- x-shadow: DSD template attributes (mode, clonable, delegatesFocus, etc.)
- x-renderer: template rendering backend (lit / vanilla / generic)

These fields address the gap where SSR/SSG engines cannot automatically
discover component rendering capabilities from CEM. Working
implementation in LessJS (github.com/lessjs-run/lessjs).

Also adds docs/x-field-conventions.md with naming rules, auto-detection
guidance, and deprecation path for x- fields.
@google-cla

google-cla Bot commented May 15, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@SisyphusZheng SisyphusZheng changed the title feat: add x-render-dependencies, x-renderer fields…for SSR/SSG metadata feat: add x-render-dependencies for SSR/SSG metadata Sep 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

SSR/SSG engines need component render dependency metadata — proposal for x-render-dependencies

1 participant