docs: add v3 deprecation audit

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.
+
 <Tabs groupId="app-upgrader">
   <TabItem label="ng update" value="ng-update">
 

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.

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

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;
   /**

packages/router/src/lib/define-route.ts

@@ -18,7 +18,7 @@ type RestrictedRoute = Omit<NgRoute, RouteOmitted> & {
 };
 
 /**
- * @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<NgRoute, RouteOmitted> & {
  *
  * ```
  * 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 {}
  * ```

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;
   /**