name	youneed-migration
description	Migrating an existing app onto the youneed stack — porting a frontend from React/Vue/Angular/Lit/Preact/Svelte to @youneed/dom (web components, html``/css`` templates, field-level reactivity), a backend from Express/Nest/Fastify/Bun/Elysia/tRPC to @youneed/server (Controller classes, onion middleware, t.* schemas), the data layer from TypeORM/Prisma/Mongoose/Sequelize to @youneed/orm-sql / @youneed/orm-nosql / @youneed/kv, and tests from Jest/Vitest/Mocha to @youneed/test. Covers the incremental/strangler strategy, the interop adapters (@youneed/dom-adapter-{react,vue,angular,preact,svelte,astro}), OpenAPI client codegen (@youneed/api-client), and the TC39-decorator/tsconfig build switch. Use this skill when planning or executing a migration TO youneed, mapping an old framework's API to youneed's, or deciding migration order and interop boundaries.
license	ISC

youneed — Migration Guide (port an existing app onto the youneed stack)

Migrations onto youneed are almost always incremental — new youneed code runs inside the old app (or vice-versa) behind an interop adapter, and you strangle the old stack piece by piece. Big-bang rewrites are the exception, not the default.

Everything here is TC39-decorator based (experimentalDecorators: false, useDefineForClassFields: false, metadata via addInitializer+WeakMap, never Symbol.metadata). Read references/tooling.md first if the source app uses legacy decorators or a non-Node runtime — the build switch gates everything else.

Source of truth: packages/{dom,server,orm-sql,orm-nosql,kv,test}/src/*, the adapter packages packages/dom-adapter-{react,vue,angular,preact,svelte,astro}/src, and packages/api-client/src. Verify a signature in source before asserting it.

Route to the reference for the task

Migrating…	Read
Overall plan — order, strangler boundaries, interop, rollback, parity checks	`references/strategy.md`
Frontend: React / Vue / Angular / Lit / Preact / Svelte → `@youneed/dom`	`references/frontend.md`
Backend: Express / Nest / Fastify / Bun / Elysia / tRPC → `@youneed/server`	`references/backend.md`
Data layer: TypeORM / Prisma / Mongoose / Sequelize / raw SQL → orm-sql / orm-nosql / kv	`references/data.md`
Tests: Jest / Vitest / Mocha / Jasmine → `@youneed/test`	`references/testing.md`
Build/runtime: tsconfig, decorator mode, bundler, Bun/Deno→Node, interop adapters, codegen	`references/tooling.md`

A full-stack migration touches several: do tooling.md (build), then the layer refs in the order strategy.md recommends. Frontend and backend can migrate independently.

The three migration shapes

Strangler (default). Stand youneed up beside the old app; route one leaf (a component, a route group) at a time through youneed; delete the old code when the last caller is gone. Interop adapter holds the seam. Lowest risk, always reversible.
Layer-by-layer. Migrate one horizontal layer end-to-end (e.g. all DTOs/schemas first, then controllers, then services). Good when the old app is already well-layered.
Big-bang. Only for small apps or greenfield-adjacent rewrites. Skip the adapters.

Ground rules for any migration

Lift schemas/DTOs first. Zod/TypeBox/class-validator/Mongoose schemas → t.* or @youneed/schema. They drive validation, the compiled serializer, and the OpenAPI doc on the server side — everything downstream depends on them.
Keep the seam adapter-shaped, not fork-shaped. Don't maintain two copies of a component/route; wrap the youneed one so the old app calls it, or vice-versa.
Prove parity before deleting. Snapshot behavior (tests, bench/load.mjs RPS/p99, visual diff) on the old path, migrate, re-run, compare, then remove the old path.
camelCase gotcha survives into migration. Ported React/Vue props with camelCase names won't bind through HTML parsing — group into one .data=${obj} or use events.
No frontend/Nest-style DI container. Angular/Nest DI does not port 1:1 — inject via constructors and a composition root. Note this early; it reshapes service wiring.

Answering style

Show the before → after pair so the mapping is unambiguous.
Name the exact interop adapter package and the wrap call (toReact, fromReact, …).
Recommend a migration order and where the strangler seam sits, not just API swaps.
Prefer the decorator style (@Component / Controller) unless the source is already functional, then show the fluent builder.

youneed — Migration Guide (port an existing app onto the youneed stack)

Route to the reference for the task

Migrating…

Read

Overall plan — order, strangler boundaries, interop, rollback, parity checks

references/strategy.md

Frontend: React / Vue / Angular / Lit / Preact / Svelte → @youneed/dom

references/frontend.md

Backend: Express / Nest / Fastify / Bun / Elysia / tRPC → @youneed/server

references/backend.md

Data layer: TypeORM / Prisma / Mongoose / Sequelize / raw SQL → orm-sql / orm-nosql / kv

references/data.md

Tests: Jest / Vitest / Mocha / Jasmine → @youneed/test

references/testing.md

Build/runtime: tsconfig, decorator mode, bundler, Bun/Deno→Node, interop adapters, codegen

references/tooling.md

A full-stack migration touches several: do tooling.md (build), then the layer refs in the order strategy.md recommends. Frontend and backend can migrate independently.

The three migration shapes

Strangler (default). Stand youneed up beside the old app; route one leaf (a component, a route group) at a time through youneed; delete the old code when the last caller is gone. Interop adapter holds the seam. Lowest risk, always reversible.

Layer-by-layer. Migrate one horizontal layer end-to-end (e.g. all DTOs/schemas first, then controllers, then services). Good when the old app is already well-layered.

Big-bang. Only for small apps or greenfield-adjacent rewrites. Skip the adapters.

Ground rules for any migration

Lift schemas/DTOs first. Zod/TypeBox/class-validator/Mongoose schemas → t.* or @youneed/schema. They drive validation, the compiled serializer, and the OpenAPI doc on the server side — everything downstream depends on them.

Keep the seam adapter-shaped, not fork-shaped. Don't maintain two copies of a component/route; wrap the youneed one so the old app calls it, or vice-versa.

Prove parity before deleting. Snapshot behavior (tests, bench/load.mjs RPS/p99, visual diff) on the old path, migrate, re-run, compare, then remove the old path.

camelCase gotcha survives into migration. Ported React/Vue props with camelCase names won't bind through HTML parsing — group into one .data=${obj} or use events.

No frontend/Nest-style DI container. Angular/Nest DI does not port 1:1 — inject via constructors and a composition root. Note this early; it reshapes service wiring.

Answering style

Show the before → after pair so the mapping is unambiguous.

Name the exact interop adapter package and the wrap call (toReact, fromReact, …).

Recommend a migration order and where the strangler seam sits, not just API swaps.

Prefer the decorator style (@Component / Controller) unless the source is already functional, then show the fluent builder.

youneed-migration