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..85477b29d --- /dev/null +++ b/apps/docs-app/docs/guides/deprecations.md @@ -0,0 +1,75 @@ +--- +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 + +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 | +| ----------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------ | +| `@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 + +### 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: + +```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 b49ebdb28..4709c3499 100644 --- a/apps/docs-app/docs/guides/migrating.md +++ b/apps/docs-app/docs/guides/migrating.md @@ -227,3 +227,13 @@ export default defineConfig(() => ({ ``` This is the recommended setup for Analog v3: one root Tailwind stylesheet, `@tailwindcss/vite` in Vite, and Analog handling component stylesheet preprocessing. + +## 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 9489ac1b9..b8adf6cc2 100644 --- a/packages/platform/src/lib/options.ts +++ b/packages/platform/src/lib/options.ts @@ -138,6 +138,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 6c7f974ca..0231a4823 100644 --- a/packages/router/src/lib/define-route.ts +++ b/packages/router/src/lib/define-route.ts @@ -18,7 +18,7 @@ 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 @@ -29,15 +29,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 84b3990d5..eb8e0cae1 100644 --- a/packages/vite-plugin-nitro/src/lib/options.ts +++ b/packages/vite-plugin-nitro/src/lib/options.ts @@ -34,9 +34,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; /**