Skip to content

Deprecate static properties field and enforce declare-free factory DX #598

@vivek7405

Description

@vivek7405

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

  1. 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.
  2. 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.
  3. 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.
  4. Clean up Type Definitions: Remove obsolete static property types and declare guidelines from packages/core/src/component.d.ts and barrel definitions.
  5. 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

  • Runtime throws an error if static properties is declared directly in class body.
  • webjs check flags any direct static properties declaration in class bodies.
  • All components in examples/blog migrated to declare-free factory pattern.
  • Obsolete documentation and comments referencing static properties + declare removed or rewritten.
  • All tests (unit, E2E, types) updated and passing green.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type
No fields configured for issues without a type.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions