From b4a9639f295f8af3716af4e3fe56508592ed74ea Mon Sep 17 00:00:00 2001 From: Ben Snyder Date: Sun, 5 Apr 2026 12:16:44 -0400 Subject: [PATCH 1/3] docs: add v3 deprecation audit --- .../docs/features/updating/overview.md | 2 + apps/docs-app/docs/guides/deprecations.md | 67 +++++++++++++++++++ apps/docs-app/docs/guides/migrating.md | 10 +++ packages/platform/src/lib/options.ts | 3 + packages/router/src/lib/define-route.ts | 9 ++- packages/vite-plugin-nitro/src/lib/options.ts | 5 +- 6 files changed, 88 insertions(+), 8 deletions(-) create mode 100644 apps/docs-app/docs/guides/deprecations.md diff --git a/apps/docs-app/docs/features/updating/overview.md b/apps/docs-app/docs/features/updating/overview.md index 533c18d51..d04907cbb 100644 --- a/apps/docs-app/docs/features/updating/overview.md +++ b/apps/docs-app/docs/features/updating/overview.md @@ -5,6 +5,8 @@ import TabItem from '@theme/TabItem'; You can use the `ng update` command for an Angular CLI workspace, or the `nx migrate` command for updating within an Nx workspace. +After updating, review the current [Deprecations and Compatibility](/docs/guides/deprecations) guide so compatibility aliases do not become your new baseline API usage. + diff --git a/apps/docs-app/docs/guides/deprecations.md b/apps/docs-app/docs/guides/deprecations.md new file mode 100644 index 000000000..afe6a6cd0 --- /dev/null +++ b/apps/docs-app/docs/guides/deprecations.md @@ -0,0 +1,67 @@ +--- +title: Deprecations and Compatibility +--- + +# Deprecations and Compatibility + +This page is the canonical deprecation audit for the current Analog v3 prerelease line. + +The goal is to keep the public surface explicit: + +- deprecated APIs stay usable only when they still protect existing projects from avoidable churn +- new docs and examples should prefer the non-deprecated API +- removals should be grouped into a major release after the migration path is already documented + +## Current public deprecations + +| Package | Deprecated API | Prefer instead | Current posture | +| ------- | -------------- | -------------- | --------------- | +| `@analogjs/router` | `defineRouteMeta()` | typed `RouteMeta` object literals | Keep exported for compatibility, but prefer `RouteMeta` in docs and new code. | +| `@analogjs/vite-plugin-nitro` | `useAPIMiddleware` | filesystem API routes in `src/server/routes/api` | Keep only as a compatibility option for older project layouts. | +| `@analogjs/platform` | `useAPIMiddleware` | filesystem API routes in `src/server/routes/api` | Same deprecation posture as Nitro because the platform option is just a passthrough. | +| `@analogjs/trpc` | `tRPCClient` | `TrpcClient` | Keep as a compatibility alias until the next major. | +| `@analogjs/trpc` | `provideTRPCClient` | `provideTrpcClient` | Keep as a compatibility alias until the next major. | +| `@analogjs/trpc` | `tRPCHeaders` | `TrpcHeaders` | Keep as a compatibility alias until the next major. | +| `@analogjs/trpc` | `ClientDataTransformerOptions` in the optional transformer union | `CombinedDataTransformer` | Keep for compatibility while the current client options shape remains supported. | + +## Upgrade guidance + +### Route metadata + +Prefer this: + +```ts +import type { RouteMeta } from '@analogjs/router'; + +export const routeMeta: RouteMeta = { + title: 'Products', +}; +``` + +Instead of wrapping the same object in `defineRouteMeta(...)`. + +### API routes + +Prefer file-based API routes under `src/server/routes/api/**`. + +`useAPIMiddleware` remains available so older projects do not have to move server files and runtime wiring in the same upgrade, but new setups should not depend on it. + +### tRPC client aliases + +Prefer the camel-cased exports: + +- `TrpcClient` +- `provideTrpcClient` +- `TrpcHeaders` + +The older `tRPC*` names remain as compatibility aliases only. + +## Next-major removal plan + +A deprecated API should be removed only when all of the following are true: + +1. The replacement is already the default in docs, examples, and generated code. +2. The replacement has a straightforward migration path. +3. The removal does not force unrelated refactors during a normal version upgrade. + +By that standard, the `tRPC*` aliases, `defineRouteMeta()`, and `useAPIMiddleware` are all reasonable next-major cleanup candidates once the current compatibility window is no longer needed. diff --git a/apps/docs-app/docs/guides/migrating.md b/apps/docs-app/docs/guides/migrating.md index 03658599f..4d5b769e1 100644 --- a/apps/docs-app/docs/guides/migrating.md +++ b/apps/docs-app/docs/guides/migrating.md @@ -192,3 +192,13 @@ export default defineConfig(({ mode }) => ({ plugins: [analog(), nxCopyAssetsPlugin(['*.md'])], })); ``` + +## Reviewing Deprecated APIs During Migration + +After the initial Analog migration is working, check the [Deprecations and Compatibility](./deprecations.md) guide before treating older helper APIs as part of the long-term app shape. + +The current audit covers: + +- route metadata helpers that are still exported for compatibility +- deprecated API middleware options in Nitro and the platform wrapper +- legacy tRPC client aliases that still ship for backwards compatibility diff --git a/packages/platform/src/lib/options.ts b/packages/platform/src/lib/options.ts index e11d4e085..72ccf17be 100644 --- a/packages/platform/src/lib/options.ts +++ b/packages/platform/src/lib/options.ts @@ -80,6 +80,9 @@ export interface Options { * Toggles internal API middleware. * If disabled, a proxy request is used to route /api * requests to / in the production server build. + * + * @deprecated Use the src/server/routes/api folder for API routes. + * Kept as a compatibility passthrough to `@analogjs/vite-plugin-nitro`. */ useAPIMiddleware?: boolean; /** diff --git a/packages/router/src/lib/define-route.ts b/packages/router/src/lib/define-route.ts index 6a7295761..5c32b0d29 100644 --- a/packages/router/src/lib/define-route.ts +++ b/packages/router/src/lib/define-route.ts @@ -12,7 +12,7 @@ type RouteOmitted = type RestrictedRoute = Omit; /** - * @deprecated Use `RouteMeta` type instead. + * @deprecated Use the `RouteMeta` type directly instead. Kept as a compatibility helper. * For more info see: https://github.com/analogjs/analog/issues/223 * * Defines additional route config metadata. This @@ -23,15 +23,14 @@ type RestrictedRoute = Omit; * * ``` * import { Component } from '@angular/core'; - * import { defineRouteMeta } from '@analogjs/router'; + * import type { RouteMeta } from '@analogjs/router'; * - * export const routeMeta = defineRouteMeta({ + * export const routeMeta: RouteMeta = { * title: 'Welcome' - * }); + * }; * * @Component({ * template: `Home`, - * standalone: true, * }) * export default class HomeComponent {} * ``` diff --git a/packages/vite-plugin-nitro/src/lib/options.ts b/packages/vite-plugin-nitro/src/lib/options.ts index ee0b4afdf..db6e64eeb 100644 --- a/packages/vite-plugin-nitro/src/lib/options.ts +++ b/packages/vite-plugin-nitro/src/lib/options.ts @@ -33,9 +33,8 @@ export interface Options { * If disabled, a proxy request is used to route /api * requests to / in the production server build. * - * @deprecated - * Use the src/server/routes/api folder - * for API routes. + * @deprecated Use the src/server/routes/api folder for API routes. + * Kept as a compatibility option for older project layouts. */ useAPIMiddleware?: boolean; } From d9ccee4f498e6de8096130ac44bb75a2bc2b376c Mon Sep 17 00:00:00 2001 From: Ben Snyder Date: Sun, 5 Apr 2026 12:25:03 -0400 Subject: [PATCH 2/3] style: format deprecation audit docs --- apps/docs-app/docs/guides/deprecations.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/docs-app/docs/guides/deprecations.md b/apps/docs-app/docs/guides/deprecations.md index afe6a6cd0..383e4978c 100644 --- a/apps/docs-app/docs/guides/deprecations.md +++ b/apps/docs-app/docs/guides/deprecations.md @@ -14,15 +14,15 @@ The goal is to keep the public surface explicit: ## Current public deprecations -| Package | Deprecated API | Prefer instead | Current posture | -| ------- | -------------- | -------------- | --------------- | -| `@analogjs/router` | `defineRouteMeta()` | typed `RouteMeta` object literals | Keep exported for compatibility, but prefer `RouteMeta` in docs and new code. | -| `@analogjs/vite-plugin-nitro` | `useAPIMiddleware` | filesystem API routes in `src/server/routes/api` | Keep only as a compatibility option for older project layouts. | -| `@analogjs/platform` | `useAPIMiddleware` | filesystem API routes in `src/server/routes/api` | Same deprecation posture as Nitro because the platform option is just a passthrough. | -| `@analogjs/trpc` | `tRPCClient` | `TrpcClient` | Keep as a compatibility alias until the next major. | -| `@analogjs/trpc` | `provideTRPCClient` | `provideTrpcClient` | Keep as a compatibility alias until the next major. | -| `@analogjs/trpc` | `tRPCHeaders` | `TrpcHeaders` | Keep as a compatibility alias until the next major. | -| `@analogjs/trpc` | `ClientDataTransformerOptions` in the optional transformer union | `CombinedDataTransformer` | Keep for compatibility while the current client options shape remains supported. | +| Package | Deprecated API | Prefer instead | Current posture | +| ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ | +| `@analogjs/router` | `defineRouteMeta()` | typed `RouteMeta` object literals | Keep exported for compatibility, but prefer `RouteMeta` in docs and new code. | +| `@analogjs/vite-plugin-nitro` | `useAPIMiddleware` | filesystem API routes in `src/server/routes/api` | Keep only as a compatibility option for older project layouts. | +| `@analogjs/platform` | `useAPIMiddleware` | filesystem API routes in `src/server/routes/api` | Same deprecation posture as Nitro because the platform option is just a passthrough. | +| `@analogjs/trpc` | `tRPCClient` | `TrpcClient` | Keep as a compatibility alias until the next major. | +| `@analogjs/trpc` | `provideTRPCClient` | `provideTrpcClient` | Keep as a compatibility alias until the next major. | +| `@analogjs/trpc` | `tRPCHeaders` | `TrpcHeaders` | Keep as a compatibility alias until the next major. | +| `@analogjs/trpc` | `ClientDataTransformerOptions` in the optional transformer union | `CombinedDataTransformer` | Keep for compatibility while the current client options shape remains supported. | ## Upgrade guidance From 9e947b322221f53e0e9bb31f886dc79727e8d5a3 Mon Sep 17 00:00:00 2001 From: Ben Snyder Date: Sun, 5 Apr 2026 12:32:46 -0400 Subject: [PATCH 3/3] docs: clarify compatibility aliases in deprecation audit --- apps/docs-app/docs/guides/deprecations.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/apps/docs-app/docs/guides/deprecations.md b/apps/docs-app/docs/guides/deprecations.md index 383e4978c..85477b29d 100644 --- a/apps/docs-app/docs/guides/deprecations.md +++ b/apps/docs-app/docs/guides/deprecations.md @@ -12,6 +12,8 @@ The goal is to keep the public surface explicit: - new docs and examples should prefer the non-deprecated API - removals should be grouped into a major release after the migration path is already documented +Some compatibility surfaces below are already formally marked deprecated in source, while others are older aliases that still need to be normalized in docs before the next major. + ## Current public deprecations | Package | Deprecated API | Prefer instead | Current posture | @@ -26,6 +28,12 @@ The goal is to keep the public surface explicit: ## Upgrade guidance +### HMR configuration + +The current `alpha` line still exposes `liveReload` in the platform, Vite plugin, and Storybook integration types. + +Treat it as a compatibility alias, not the long-term API shape. New docs and examples should normalize on `hmr` naming as the v3 direction, even where the current type surface still accepts `liveReload`. + ### Route metadata Prefer this: