From ab62d179091f470ba58547cc17ad07f90aa90645 Mon Sep 17 00:00:00 2001 From: BilalG1 Date: Wed, 27 May 2026 18:37:12 -0700 Subject: [PATCH] update deprecated msgs (#1510) --- ## Summary by cubic Added Hexclave-branded aliases for public Stack APIs and updated deprecation guidance to point to `@hexclave/*` and the migration guide. Deprecation tags now live on source declarations so they survive dts bundling; behavior unchanged. - **Refactors** - Added `HexclaveHandler`, `HexclaveProvider`, `HexclaveTheme`, `useHexclaveApp`, and `HexclaveConfig`/`defineHexclaveConfig`; kept `Stack*` as deprecated aliases. - Moved deprecation JSDoc to original declarations and adjusted `template/src/index.ts` re-exports; default exports preserved for back-compat. Written for commit 0077c8a56022948156aa8ba324bd51c97aab7527. Summary will update on new commits. Review in cubic ## Summary by CodeRabbit * **Refactor** * Primary exports rebranded to Hexclave names (handlers, providers, theme, config, hooks) with deprecated Stack aliases preserved for compatibility. * Provider/theme/handler exports standardized to named exports and a single default export per component. * **Documentation** * Improved deprecation guidance: legacy Stack symbols now carry deprecation JSDoc pointing to Hexclave alternatives and migration docs. * **Behavior** * Hook useStackApp now delegates to the new useHexclaveApp; useUser reads from the Hexclave-based hook. [![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/hexclave/stack-auth/pull/1510?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack) --- packages/stack-shared/src/config-authoring.ts | 10 +++++ .../src/components-page/stack-handler.tsx | 17 +++++++- packages/template/src/index.ts | 31 ++++++--------- packages/template/src/lib/hooks.tsx | 39 ++++++++++++------- .../stack-app/apps/interfaces/admin-app.ts | 4 ++ .../stack-app/apps/interfaces/client-app.ts | 5 +++ .../stack-app/apps/interfaces/server-app.ts | 4 ++ packages/template/src/lib/stack-app/index.ts | 14 ++----- .../template/src/providers/stack-provider.tsx | 16 ++++++-- .../template/src/providers/theme-provider.tsx | 7 +++- 10 files changed, 97 insertions(+), 50 deletions(-) diff --git a/packages/stack-shared/src/config-authoring.ts b/packages/stack-shared/src/config-authoring.ts index 2f97fe6a5..888ee698d 100644 --- a/packages/stack-shared/src/config-authoring.ts +++ b/packages/stack-shared/src/config-authoring.ts @@ -2,8 +2,12 @@ import type { BranchConfigNormalizedOverride } from "./config/schema"; type StackConfigObject = BranchConfigNormalizedOverride; export const showOnboardingStackConfigValue = "show-onboarding"; +/** @deprecated Use `HexclaveConfig` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackConfig = StackConfigObject | typeof showOnboardingStackConfigValue; +// Hexclave alias — same shape, declared separately so it doesn't inherit the deprecation tag. +export type HexclaveConfig = StackConfigObject | typeof showOnboardingStackConfigValue; + type StrictConfigShape = Expected extends readonly unknown[] ? Actual extends readonly unknown[] @@ -22,6 +26,12 @@ type StrictStackConfig = ? T & StrictConfigShape : T; +/** @deprecated Use `defineHexclaveConfig` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export function defineStackConfig(config: StrictStackConfig): T { return config; } + +// Hexclave alias — separate function so it does not inherit the deprecation tag. +export function defineHexclaveConfig(config: StrictStackConfig): T { + return config; +} diff --git a/packages/template/src/components-page/stack-handler.tsx b/packages/template/src/components-page/stack-handler.tsx index c2fe634f6..42fd4c468 100644 --- a/packages/template/src/components-page/stack-handler.tsx +++ b/packages/template/src/components-page/stack-handler.tsx @@ -6,7 +6,7 @@ import { BaseHandlerProps, StackHandlerClient } from "./stack-handler-client"; -export default function StackHandler({ app, routeProps, params, searchParams, ...props }: BaseHandlerProps & { location?: string } & { +type StackHandlerProps = BaseHandlerProps & { location?: string } & { /** * @deprecated The app parameter is no longer necessary. You can safely remove it. */ @@ -26,6 +26,19 @@ export default function StackHandler({ app, routeProps, params, searchParams, .. * @deprecated The searchParams parameter is no longer necessary. You can safely remove it. */ searchParams?: any, -}) { +}; + +function HandlerImpl({ app, routeProps, params, searchParams, ...props }: StackHandlerProps) { return ; } + +// Non-deprecated Hexclave-branded export. +export const HexclaveHandler = HandlerImpl; + +/** @deprecated Use `HexclaveHandler` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ +export const StackHandler = HandlerImpl; + +// Default export preserved for backwards compatibility (legacy `as`-rename re-exports). +// Points at the deprecated alias so that `import StackHandler from ".../stack-handler"` still +// surfaces the deprecation. Internal re-exports in template/src/index.ts use the named exports. +export default StackHandler; diff --git a/packages/template/src/index.ts b/packages/template/src/index.ts index 61340d1db..fa635caa8 100644 --- a/packages/template/src/index.ts +++ b/packages/template/src/index.ts @@ -6,30 +6,21 @@ import "./internal/deprecation-warning"; export * from './lib/stack-app'; export { getConvexProvidersConfig } from "./integrations/convex"; -// Hexclave aliases — same symbols under the new brand name (see RENAME-TO-HEXCLAVE.md, Tier 1) -export type { StackConfig as HexclaveConfig } from "@stackframe/stack-shared/config"; -export { defineStackConfig as defineHexclaveConfig } from "@stackframe/stack-shared/config"; -/** @deprecated Use `HexclaveConfig` instead — same symbol, new brand name. */ -export type { StackConfig } from "@stackframe/stack-shared/config"; -/** @deprecated Use `defineHexclaveConfig` instead — same symbol, new brand name. */ -export { defineStackConfig } from "@stackframe/stack-shared/config"; +// Hexclave aliases and legacy Stack* names — @deprecated JSDoc lives on the original +// declarations in @stackframe/stack-shared/config so it survives dts bundling +// (per-specifier JSDoc on re-exports does not). +export type { HexclaveConfig, StackConfig } from "@stackframe/stack-shared/config"; +export { defineHexclaveConfig, defineStackConfig } from "@stackframe/stack-shared/config"; // IF_PLATFORM react-like export type { AnalyticsOptions, AnalyticsReplayOptions } from "./lib/stack-app/apps/implementations/session-replay"; -// Hexclave aliases — same symbols under the new brand name (see RENAME-TO-HEXCLAVE.md, Tier 1) -export { default as HexclaveHandler } from "./components-page/stack-handler"; -export { useStackApp as useHexclaveApp } from "./lib/hooks"; -export { default as HexclaveProvider } from "./providers/stack-provider"; -export { StackTheme as HexclaveTheme } from './providers/theme-provider'; -/** @deprecated Use `HexclaveHandler` instead — same symbol, new brand name. */ -export { default as StackHandler } from "./components-page/stack-handler"; -/** @deprecated Use `useHexclaveApp` instead — same symbol, new brand name. */ -export { useStackApp } from "./lib/hooks"; +// Hexclave aliases and legacy Stack* names — @deprecated JSDoc lives on the original +// declarations in the source files (so it survives dts bundling). +export { HexclaveHandler, StackHandler } from "./components-page/stack-handler"; +export { useHexclaveApp, useStackApp } from "./lib/hooks"; +export { HexclaveProvider, StackProvider } from "./providers/stack-provider"; +export { HexclaveTheme, StackTheme } from './providers/theme-provider'; export { useUser } from "./lib/hooks"; -/** @deprecated Use `HexclaveProvider` instead — same symbol, new brand name. */ -export { default as StackProvider } from "./providers/stack-provider"; -/** @deprecated Use `HexclaveTheme` instead — same symbol, new brand name. */ -export { StackTheme } from './providers/theme-provider'; export { AccountSettings } from "./components-page/account-settings"; export { AuthPage } from "./components-page/auth-page"; diff --git a/packages/template/src/lib/hooks.tsx b/packages/template/src/lib/hooks.tsx index 99e29bfa8..200eb1bcf 100644 --- a/packages/template/src/lib/hooks.tsx +++ b/packages/template/src/lib/hooks.tsx @@ -16,9 +16,9 @@ export function useUser(options: GetUserOptions & { or: 'redirect' | 'throw' }): export function useUser(options: GetUserOptions & { projectIdMustMatch: "internal" }): CurrentInternalUser | null; export function useUser(options?: GetUserOptions): CurrentUser | CurrentInternalUser | null; export function useUser(options: GetUserOptions = {}): CurrentUser | CurrentInternalUser | null { - const stackApp = useStackApp(options); + const stackApp = useHexclaveApp(options); if (options.projectIdMustMatch && stackApp.projectId !== options.projectIdMustMatch) { - throw new Error("Unexpected project ID in useStackApp: " + stackApp.projectId); + throw new Error("Unexpected project ID in useHexclaveApp: " + stackApp.projectId); } if (options.projectIdMustMatch === "internal") { return stackApp.useUser(options) as CurrentInternalUser; @@ -27,22 +27,33 @@ export function useUser(options: GetUserOptions = {}): CurrentUser | CurrentInte } } +/** + * Returns the current Hexclave app associated with the HexclaveProvider. + * + * @returns the current Hexclave app + */ +export function useHexclaveApp(options: { projectIdMustMatch?: ProjectId } = {}): StackClientApp { + if (typeof useContext !== "function") { + throw new Error("useHexclaveApp() can only be used in a React Client Component. Make sure you're not calling it from a Server Component, or any other environment."); + } + const context = useContext(StackContext); + if (context === null) { + throw new Error("useHexclaveApp must be used within a HexclaveProvider"); + } + const stackApp = context.app; + if (options.projectIdMustMatch && stackApp.projectId !== options.projectIdMustMatch) { + throw new Error("Unexpected project ID in useHexclaveApp: " + stackApp.projectId); + } + return stackApp as StackClientApp; +} + /** * Returns the current Stack app associated with the StackProvider. * + * @deprecated Use `useHexclaveApp` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. + * * @returns the current Stack app */ export function useStackApp(options: { projectIdMustMatch?: ProjectId } = {}): StackClientApp { - if (typeof useContext !== "function") { - throw new Error("useStackApp() can only be used in a React Client Component. Make sure you're not calling it from a Server Component, or any other environment."); - } - const context = useContext(StackContext); - if (context === null) { - throw new Error("useStackApp must be used within a StackProvider"); - } - const stackApp = context.app; - if (options.projectIdMustMatch && stackApp.projectId !== options.projectIdMustMatch) { - throw new Error("Unexpected project ID in useStackApp: " + stackApp.projectId); - } - return stackApp as StackClientApp; + return useHexclaveApp(options); } diff --git a/packages/template/src/lib/stack-app/apps/interfaces/admin-app.ts b/packages/template/src/lib/stack-app/apps/interfaces/admin-app.ts index b04e44079..104f41485 100644 --- a/packages/template/src/lib/stack-app/apps/interfaces/admin-app.ts +++ b/packages/template/src/lib/stack-app/apps/interfaces/admin-app.ts @@ -56,6 +56,7 @@ import type { AdminSessionReplay, ListSessionReplayChunksOptions, ListSessionRep export type { AdminSessionReplay, AdminSessionReplayChunk, ListSessionReplaysOptions, ListSessionReplaysResult, ListSessionReplayChunksOptions, ListSessionReplayChunksResult, SessionReplayAllEventsResult } from "../../session-replays"; +/** @deprecated Use `HexclaveAdminAppConstructorOptions` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackAdminAppConstructorOptions = ( & StackServerAppConstructorOptions & { @@ -65,6 +66,7 @@ export type StackAdminAppConstructorOptions = ( & AsyncStoreProperty<"project", [], AdminProject, false> & AsyncStoreProperty<"internalApiKeys", [], InternalApiKey[], true> @@ -170,6 +172,7 @@ export type StackAdminApp ); +/** @deprecated Use `HexclaveAdminAppConstructor` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackAdminAppConstructor = { new < HasTokenStore extends boolean, @@ -181,4 +184,5 @@ export type HexclaveAdminAppConstructorOptions = StackAdminApp; export type HexclaveAdminAppConstructor = StackAdminAppConstructor; export const HexclaveAdminApp: HexclaveAdminAppConstructor = _StackAdminAppImpl; +/** @deprecated Use `HexclaveAdminApp` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export const StackAdminApp: StackAdminAppConstructor = HexclaveAdminApp; diff --git a/packages/template/src/lib/stack-app/apps/interfaces/client-app.ts b/packages/template/src/lib/stack-app/apps/interfaces/client-app.ts index aa053e670..1cdb81619 100644 --- a/packages/template/src/lib/stack-app/apps/interfaces/client-app.ts +++ b/packages/template/src/lib/stack-app/apps/interfaces/client-app.ts @@ -9,6 +9,7 @@ import { ProjectCurrentUser, SyncedPartialUser, TokenPartialUser } from "../../u import { _StackClientAppImpl } from "../implementations"; import { AnalyticsOptions } from "../implementations/session-replay"; +/** @deprecated Use `HexclaveClientAppConstructorOptions` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackClientAppConstructorOptions = { baseUrl?: string | { browser: string, server: string }, extraRequestHeaders?: Record, @@ -46,11 +47,13 @@ export type StackClientAppConstructorOptions = StackClientAppConstructorOptions & { inheritsFrom?: undefined } & { uniqueIdentifier: string, // note: if you add more fields here, make sure to ensure the checkString in the constructor has/doesn't have them }; +/** @deprecated Use `HexclaveClientApp` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackClientApp = ( & { readonly projectId: ProjectId, @@ -153,6 +156,7 @@ export type StackClientApp>}`]: (options?: RedirectToOptions) => Promise } & AuthLike ); +/** @deprecated Use `HexclaveClientAppConstructor` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackClientAppConstructor = { new < TokenStoreType extends string, @@ -172,4 +176,5 @@ export type HexclaveClientAppJson = StackClientApp; export type HexclaveClientAppConstructor = StackClientAppConstructor; export const HexclaveClientApp: HexclaveClientAppConstructor = _StackClientAppImpl; +/** @deprecated Use `HexclaveClientApp` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export const StackClientApp: StackClientAppConstructor = HexclaveClientApp; diff --git a/packages/template/src/lib/stack-app/apps/interfaces/server-app.ts b/packages/template/src/lib/stack-app/apps/interfaces/server-app.ts index 6a71a20a6..e272358af 100644 --- a/packages/template/src/lib/stack-app/apps/interfaces/server-app.ts +++ b/packages/template/src/lib/stack-app/apps/interfaces/server-app.ts @@ -11,10 +11,12 @@ import { _StackServerAppImpl } from "../implementations"; import { StackClientApp, StackClientAppConstructorOptions } from "./client-app"; +/** @deprecated Use `HexclaveServerAppConstructorOptions` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackServerAppConstructorOptions = StackClientAppConstructorOptions & { secretServerKey?: string, }; +/** @deprecated Use `HexclaveServerApp` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackServerApp = ( & { createTeam(data: ServerTeamCreateOptions): Promise, @@ -116,6 +118,7 @@ export type StackServerApp & StackClientApp ); +/** @deprecated Use `HexclaveServerAppConstructor` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export type StackServerAppConstructor = { new < TokenStoreType extends string, @@ -128,4 +131,5 @@ export type HexclaveServerAppConstructorOptions = StackServerApp; export type HexclaveServerAppConstructor = StackServerAppConstructor; export const HexclaveServerApp: HexclaveServerAppConstructor = _StackServerAppImpl; +/** @deprecated Use `HexclaveServerApp` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ export const StackServerApp: StackServerAppConstructor = HexclaveServerApp; diff --git a/packages/template/src/lib/stack-app/index.ts b/packages/template/src/lib/stack-app/index.ts index 2e482be93..11a415f4c 100644 --- a/packages/template/src/lib/stack-app/index.ts +++ b/packages/template/src/lib/stack-app/index.ts @@ -6,11 +6,10 @@ export { // Legacy Stack* aliases — same runtime symbols, kept for backwards compatibility. // Prefer the Hexclave* equivalents in new code. See RENAME-TO-HEXCLAVE.md (Tier 1). -/** @deprecated Use `HexclaveAdminApp` instead — same symbol, new brand name. */ +// The @deprecated JSDoc lives on the original declarations in ./apps/interfaces/*.ts +// so it survives dts bundling (per-specifier JSDoc on re-exports does not). export { StackAdminApp } from "./apps"; -/** @deprecated Use `HexclaveClientApp` instead — same symbol, new brand name. */ export { StackClientApp } from "./apps"; -/** @deprecated Use `HexclaveServerApp` instead — same symbol, new brand name. */ export { StackServerApp } from "./apps"; // HexclaveAdminApp / HexclaveClientApp / HexclaveServerApp are already exported above as values @@ -26,19 +25,14 @@ export type { HexclaveServerAppConstructorOptions, } from "./apps"; -/** @deprecated Use `HexclaveAdminAppConstructor` instead — same symbol, new brand name. */ +// Legacy Stack* type aliases — @deprecated tags live on the original declarations +// in ./apps/interfaces/*.ts (per-specifier JSDoc on re-exports doesn't survive dts bundling). export type { StackAdminAppConstructor } from "./apps"; -/** @deprecated Use `HexclaveAdminAppConstructorOptions` instead — same symbol, new brand name. */ export type { StackAdminAppConstructorOptions } from "./apps"; -/** @deprecated Use `HexclaveClientAppConstructor` instead — same symbol, new brand name. */ export type { StackClientAppConstructor } from "./apps"; -/** @deprecated Use `HexclaveClientAppConstructorOptions` instead — same symbol, new brand name. */ export type { StackClientAppConstructorOptions } from "./apps"; -/** @deprecated Use `HexclaveClientAppJson` instead — same symbol, new brand name. */ export type { StackClientAppJson } from "./apps"; -/** @deprecated Use `HexclaveServerAppConstructor` instead — same symbol, new brand name. */ export type { StackServerAppConstructor } from "./apps"; -/** @deprecated Use `HexclaveServerAppConstructorOptions` instead — same symbol, new brand name. */ export type { StackServerAppConstructorOptions } from "./apps"; export type { diff --git a/packages/template/src/providers/stack-provider.tsx b/packages/template/src/providers/stack-provider.tsx index 38f60c769..6bbf60e5f 100644 --- a/packages/template/src/providers/stack-provider.tsx +++ b/packages/template/src/providers/stack-provider.tsx @@ -90,10 +90,20 @@ function ReactStackProvider({ } // END_PLATFORM +// Pick the platform-appropriate provider implementation. Only the active branch's +// line is preserved by the platform-stripping script when generating per-platform SDKs. +// The /* ... */ block hides the inactive branches from the template's TypeScript compiler. // IF_PLATFORM next -export default NextStackProvider; +const ActiveProvider = NextStackProvider; /* ELSE_IF_PLATFORM tanstack-start -export default TanStackStartStackProvider; +const ActiveProvider = TanStackStartStackProvider; ELSE_PLATFORM -export default ReactStackProvider; +const ActiveProvider = ReactStackProvider; END_PLATFORM */ + +// Named exports live outside the platform conditional so the @deprecated JSDoc can +// use a /** ... */ block without colliding with the outer comment terminator. +export const HexclaveProvider = ActiveProvider; +/** @deprecated Use `HexclaveProvider` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. */ +export const StackProvider = ActiveProvider; +export default ActiveProvider; diff --git a/packages/template/src/providers/theme-provider.tsx b/packages/template/src/providers/theme-provider.tsx index b30238546..a8d6678a6 100644 --- a/packages/template/src/providers/theme-provider.tsx +++ b/packages/template/src/providers/theme-provider.tsx @@ -77,7 +77,7 @@ function convertColorsToCSS(theme: Theme) { } -export function StackTheme({ +export function HexclaveTheme({ theme, children, nonce, @@ -109,3 +109,8 @@ export function StackTheme({ ); } + +/** + * @deprecated Use `HexclaveTheme` from the `@hexclave/*` package instead — same symbol, new brand name. See https://docs.hexclave.com/migration. + */ +export const StackTheme = HexclaveTheme;