mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-16 21:08:38 +08:00
7125a9eff4
Source rename across the monorepo. Every publishable package now ships
under its @hexclave/* name natively, no rewrite-at-publish indirection.
Workflow + tooling:
- Delete scripts/rewrite-packages-to-hexclave.ts (one-shot mirror).
- Remove the mirror-publish block from .github/workflows/npm-publish.yaml.
The remaining `pnpm publish -r` step publishes @hexclave/* natively.
- Flip the auto-bump changeset target from @stackframe/stack to
@hexclave/next so 'Update package versions on dev' keeps working.
- Delete packages/template/src/internal/deprecation-warning.ts and its
imports — @hexclave/* never warns about itself, and after PR 3 no
@stackframe/* artifact is ever built from source again.
Package renames (publishable):
@stackframe/react → @hexclave/react
@stackframe/stack → @hexclave/next
@stackframe/js → @hexclave/js
@stackframe/stack-shared → @hexclave/shared
@stackframe/stack-ui → @hexclave/ui
@stackframe/stack-sc → @hexclave/sc
@stackframe/stack-cli → @hexclave/cli
@stackframe/tanstack-start → @hexclave/tanstack-start
@stackframe/dashboard-ui-components → @hexclave/dashboard-ui-components
Internal monorepo packages (private, never published) also renamed for
brand consistency: backend, dashboard, docs, mcp, skills, e2e-tests,
example apps, the swift-sdk, the monorepo root, etc. Cost is mechanical;
payoff is no stray @stackframe/* names left under apps/, examples/, sdks/.
Carve-outs intentionally kept under their legacy names:
- @stackframe/emails — virtual module imported by customer-stored email
templates; the renderer in apps/backend/src/lib/email-rendering.tsx
dual-aliases both names to the same backing module indefinitely.
- @stackframe/template — internal codegen source, never published; per
docs-mintlify/migration.mdx 'internal packages keep names'.
- @stackframe/init-stack — deprecated; now marked private: true so the
last published version on npm continues to serve old install commands
but the workspace stops publishing it.
Backward-compat detection (so projects still on the last @stackframe/*
release keep working):
- packages/stack-shared/src/config-rendering.ts — CONFIG_IMPORT_PACKAGES
table includes both @hexclave/* (canonical, first match wins) and
legacy @stackframe/* names. Function renamed
detectStackframeImportPackage → detectConfigImportPackage.
- apps/dashboard/src/lib/github-config-push.ts — import detection regex
now matches both @hexclave/<name> and @stackframe/<name>, hexclave
preferred.
Versions: every renamed package reset to 1.0.0 in source. The repo's
existing 'bump versions before merging to main' flow will move them to
1.0.1 on the first publish run, so the dual-publish 1.0.0 from PR 2 is
not overwritten.
Other touch-ups discovered during sweep:
- Root package.json: 'fern' script filter was @stackframe/docs (legacy
typo, never resolved) → @hexclave/docs.
- README.md contributor note: @stackframe/XYZ → @hexclave/XYZ.
- packages/stack-cli/package.json: register `hexclave` bin alongside
the legacy `stack` bin so `npx @hexclave/cli init` works on the
natively-published artifact (PR 1481's rewrite script did this at
publish time; now it's in source).
- packages/template/package-template.json: per-platform names + version
flipped to hexclave + 1.0.0 to stay in sync with generated package.json.
- docs/package.json (legacy fumadocs folder, otherwise carved out of the
brand sweep): workspace deps and name updated minimally so `pnpm
install` resolves — content (MDX) intentionally untouched per the
PR 2 scoping decision.
Carve-out files (skipped entirely by the sweep, intentional history):
- docs-mintlify/migration.mdx — teaches the rename, references both.
- RENAME-TO-HEXCLAVE.md — planning doc, references both indefinitely.
- legacy docs/ folder — content untouched per PR 2 carve-out.
generate-sdks regenerated packages/{react,stack,js} from template.
pnpm-lock.yaml regenerated. Typecheck green on stack-shared, stack, js,
react. Dashboard typecheck has pre-existing 'X is of type unknown'
errors that need to be investigated separately (likely a local
node_modules build state issue, not source).
|
||
|---|---|---|
| .. | ||
| src | ||
| package.json | ||
| README.md | ||
Hexclave SDK Specification
This folder contains the specification for Hexclave's SDKs.
When writing this specification, try to write imperative pseudocode as much as possible (be explicit about what things are named, etc.).
Notation
The spec files use the following notation:
| Notation | Meaning |
|---|---|
[authenticated] |
Include access token, handle 401 refresh |
[server-only] |
Requires secretServerKey |
[BROWSER-LIKE] |
Requires browser or browser-like environment (browser, WebView, in-app browser). On mobile, open an in-app browser (ASWebAuthenticationSession on iOS, Custom Tabs on Android). On desktop, open the system browser with a registered URL scheme. |
[BROWSER-ONLY] |
Strictly requires browser environment (DOM, window object) |
[CLI-ONLY] |
Only in languages/platforms with an interactive terminal |
[JS-ONLY] |
Only available in the JavaScript SDK |
{ field, field } |
Request body (JSON) |
"Does not error" |
Function handles errors internally |
"Errors: ..." |
Lists possible errors with code/message |
See _utilities.spec.md for more details.
Language Adaptation
The languages should adapt:
- Naming conventions: camelCase (JS), snake_case (Python), PascalCase (Go), etc.
- Async patterns: Promises (JS), async/await (Python), goroutines (Go)
- Error handling: Exceptions vs Result types (language preference)
- Parameter conventions: Objects vs. kwargs, etc.
- Framework hooks: Eg. for React, add
use*equivalents toget*/list*methods - Everything else, wherever it makes sense: Every language is unique and the patterns will differ. If you have to decide between what's idiomatic in a language vs. what was done in the Hexclave SDK for other languages, use the idiomatic pattern.
Implementation Notes
Object Construction
When constructing SDK objects (User, Team, etc.) from API responses:
- Map naming conventions to your language's naming convention
- Objects should hold a reference to the SDK client for making API calls
- Objects can be mutable or immutable based on language conventions
update()methods should update local properties after successful API call
Caching
Normal functions should not cache. Some frameworks, like React, have hooks that require caching; for these, require explicit guidance.
Pagination
Most list* methods support pagination:
- Request with
cursorandlimitquery params - Response includes
pagination: { next_cursor?: string } next_cursoris null or absent when no more pages- Default limit is typically 100
- Note that not all backend APIs support pagination, and some just return all items at once.
Date/Time Formats
- API uses milliseconds since epoch for timestamps (e.g.,
signed_up_at_millis) - Convert to your language's native Date/DateTime type