Problem
We want to fully commit to the declare-free reactive property DX (extends WebComponent({ count: Number })) and drop support for the old static properties = { ... } + declare pattern. Since we do not have any active external webjs users yet, we do not need to worry about backward compatibility. Keeping both patterns doubles the API surface, increases maintenance costs, and adds cognitive overhead.
Design / approach
- Runtime Enforcement: Modify the
WebComponent runtime base class (packages/core/src/component.js) to throw a runtime error if a component class defines static properties directly in its own class body.
- Convention Check (
webjs check): Replace the old reactive-props-use-declare lint rule in packages/server/src/check.js with a new rule that flags any direct static properties declarations inside class bodies, directing developers to use the factory pattern instead.
- Migrate Dogfood Apps: Update the existing webjs applications and examples in the monorepo (specifically the
examples/blog components) to use the declare-free factory pattern.
- Clean up Type Definitions: Remove obsolete static property types and
declare guidelines from packages/core/src/component.d.ts and barrel definitions.
- Update Templates and Docs: Remove all references to the old pattern from scaffold templates, instructions, and documentation files.
Implementation notes (for the implementing agent)
- Where to edit:
- Runtime check:
packages/core/src/component.js inside _initializeProperties() or constructor.
- Lint check:
packages/server/src/check.js and packages/server/src/js-scan.js.
- Blog example components:
examples/blog/components/*.ts and examples/blog/modules/**/*.ts.
- Documentation:
docs/app/docs/components/page.ts, docs/app/docs/editor-setup/page.ts, docs/app/docs/troubleshooting/page.ts, AGENTS.md, agent-docs/components.md, agent-docs/lit-muscle-memory-gotchas.md.
- Templates:
packages/cli/templates/AGENTS.md, packages/cli/templates/CONVENTIONS.md.
- Landmines:
- Ensure that throwing a runtime error doesn't break other internal base class inheritance if any.
- Ensure all E2E, unit, and type-check tests are updated to reflect the removal of the old pattern (e.g., updating files in
packages/server/test/check/check.test.js and test/types/component-types.test-d.ts that test the old pattern).
- Invariants to respect:
- Do not use build steps; keep source-is-runtime.
Acceptance criteria
Problem
We want to fully commit to the declare-free reactive property DX (
extends WebComponent({ count: Number })) and drop support for the oldstatic properties = { ... }+declarepattern. Since we do not have any active external webjs users yet, we do not need to worry about backward compatibility. Keeping both patterns doubles the API surface, increases maintenance costs, and adds cognitive overhead.Design / approach
WebComponentruntime base class (packages/core/src/component.js) to throw a runtime error if a component class definesstatic propertiesdirectly in its own class body.webjs check): Replace the oldreactive-props-use-declarelint rule inpackages/server/src/check.jswith a new rule that flags any directstatic propertiesdeclarations inside class bodies, directing developers to use the factory pattern instead.examples/blogcomponents) to use the declare-free factory pattern.declareguidelines frompackages/core/src/component.d.tsand barrel definitions.Implementation notes (for the implementing agent)
packages/core/src/component.jsinside_initializeProperties()or constructor.packages/server/src/check.jsandpackages/server/src/js-scan.js.examples/blog/components/*.tsandexamples/blog/modules/**/*.ts.docs/app/docs/components/page.ts,docs/app/docs/editor-setup/page.ts,docs/app/docs/troubleshooting/page.ts,AGENTS.md,agent-docs/components.md,agent-docs/lit-muscle-memory-gotchas.md.packages/cli/templates/AGENTS.md,packages/cli/templates/CONVENTIONS.md.packages/server/test/check/check.test.jsandtest/types/component-types.test-d.tsthat test the old pattern).Acceptance criteria
static propertiesis declared directly in class body.webjs checkflags any directstatic propertiesdeclaration in class bodies.examples/blogmigrated to declare-free factory pattern.static properties + declareremoved or rewritten.