webcomponents / webcomponents/custom-elements-manifest

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

Open
#147 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
502
Forks
27
PR merge metrics
No merged PRs in 30d

Description

## Problem

Custom Elements Manifest describes a component's public API, but it has no shared field for the direct custom elements referenced by that component's own render output.

SSR and SSG tools may need those direct edges before rendering so they can prepare the required component definitions, resolve the transitive dependency graph, detect cycles, and avoid discovering nested components through repeated render attempts.

For example, if `` renders `` and ``, a manifest could expose those direct dependencies:

```json
{
"kind": "class",
"name": "MyCard",
"tagName": "my-card",
"x-render-dependencies": ["my-button", "my-icon"]
}
```

## Proposal

Add an optional experimental field to `CustomElement`:

```ts
'x-render-dependencies'?: string[];
```

The array contains **direct dependencies only**. Consumers are responsible for resolving transitive dependencies and handling cycles.

The `x-` prefix is proposed as an experimental extension convention, following the earlier custom-data discussion in #38. If maintainers prefer a standard field such as `renderDependencies`, I am happy to change the name.

## Production and consumption

Producers can supply the field explicitly. An analyzer may also infer it on a best-effort basis from framework templates or parsed HTML, but static inference is not expected to be complete and an explicit value should be able to override it.

The proposal intentionally does not prescribe a regular expression for valid custom element names. The HTML Standard's valid custom element name rules are broader than a simple ASCII tag-name pattern, and validation can be handled independently from this field's graph semantics.

## Motivating implementation

[OpenElement](https://github.com/open-element/openelement) has a working nested-component rendering path where the renderer needs an admitted set of component tags and their registered compiled definitions:

- [`packages/element/src/public-runtime.ts`](https://github.com/open-element/openelement/blob/main/packages/element/src/public-runtime.ts)
- [`packages/element/src/internal/compiled/server/index.ts`](https://github.com/open-element/openelement/blob/main/packages/element/src/internal/compiled/server/index.ts)
- [`packages/element/__tests__/compiled-server/compiled-composition.test.ts`](https://github.com/open-element/openelement/blob/main/packages/element/__tests__/compiled-server/compiled-composition.test.ts)

This is implementation evidence for the metadata need, not a claim that every SSR engine has the same registration algorithm.

## Scope

This issue is intentionally limited to `x-render-dependencies`. Renderer selection, hydration capability, and shadow-root configuration are separate concerns and are not part of this proposal.

## Validation boundary

The associated PR adds the field to the TypeScript schema and generated JSON Schema, plus a positive example test. It does not claim that incorrect values are currently rejected in every declaration union: #138 tracks the existing `anyOf` validation ambiguity.

## Open questions

1. Should the field use the experimental `x-render-dependencies` name, or a standard unprefixed name?
2. Is direct-only dependency data the right contract?
3. Should explicit metadata override analyzer inference?

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.