Init stack more args by BilalG1 · Pull Request #892 · stack-auth/stack-auth

BilalG1 · 2025-09-11T17:19:59Z

High-level PR Summary

This PR restructures how Stack apps are initialized by moving from a single stack.ts file to a directory structure with separate client and server files (stack/client.ts and stack/server.ts). The changes update all import paths throughout the codebase and documentation to reflect this new structure. Additionally, the PR adds command-line arguments to the init-stack tool to allow specifying project ID and publishable client key during initialization, which enhances the developer experience by allowing these values to be pre-populated in the generated configuration files.

⏱️ Estimated Review Time: 1h 15m

💡 Review Order Suggestion

Order	File Path
1	`packages/init-stack/src/index.ts`
2	`packages/init-stack/package.json`
3	`docs/templates/getting-started/setup.mdx`
4	`apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/(overview)/setup-page.tsx`
5	`docs/templates/getting-started/example-pages.mdx`
6	`docs/templates/getting-started/users.mdx`
7	`docs/templates/components/stack-handler.mdx`
8	`docs/templates/components/stack-provider.mdx`
9	`docs/templates/concepts/oauth.mdx`
10	`docs/templates/concepts/permissions.mdx`
11	`docs/templates/concepts/user-onboarding.mdx`
12	`docs/templates/customization/custom-pages.mdx`
13	`docs/templates/customization/page-examples/forgot-password.mdx`
14	`docs/templates/customization/page-examples/password-reset.mdx`
15	`docs/templates/others/supabase.mdx`
16	`apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx`

⚠️ Inconsistent Changes Detected

File Path	Warning
`apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx`	This file only removes a Separator component with no relation to the stack file structure changes or command-line arguments that are the focus of this PR.

Important

Renamed stack.ts to stack/client.ts and stack/server.ts across the codebase, updated init-stack package with new options, and adjusted documentation accordingly.

File Renames:
- Rename stack.ts to stack/client.ts and stack/server.ts in setup-page.tsx, stack-handler.mdx, stack-provider.mdx, oauth.mdx, permissions.mdx, user-onboarding.mdx, custom-pages.mdx, forgot-password.mdx, password-reset.mdx, example-pages.mdx, setup.mdx, users.mdx, supabase.mdx.
Package Updates:
- Add --project-id and --publishable-client-key options to init-stack in index.ts.
- Update package.json scripts to include test-run-keys-next and test-run-keys-js for testing with project ID and client key.
Miscellaneous:
- Remove Separator component from page-client.tsx.
- Update documentation to reflect file path changes.

^{This description was created by}^{for 27dbbc1. You can customize this summary. It will automatically update as commits are pushed.}

Review by RecurseML

🔍 Review performed on 0c4958a..27dbbc1

✨ No bugs found, your code is sparkling clean

✅ Files analyzed, no issues (3)

• packages/init-stack/src/index.ts
• apps/dashboard/src/app/(main)/(protected)/projects/[projectId]/(overview)/setup-page.tsx
• apps/dashboard/src/app/(main)/(protected)/(outside-dashboard)/new-project/page-client.tsx

⏭️ Files skipped (trigger manually) (13)

Locations	Trigger Analysis
`docs/templates/components/stack-handler.mdx`
`docs/templates/components/stack-provider.mdx`
`docs/templates/concepts/oauth.mdx`
`docs/templates/concepts/permissions.mdx`
`docs/templates/concepts/user-onboarding.mdx`
`docs/templates/customization/custom-pages.mdx`
`docs/templates/customization/page-examples/forgot-password.mdx`
`docs/templates/customization/page-examples/password-reset.mdx`
`docs/templates/getting-started/example-pages.mdx`
`docs/templates/getting-started/setup.mdx`
`docs/templates/getting-started/users.mdx`
`docs/templates/others/supabase.mdx`
`packages/init-stack/package.json`

Summary by CodeRabbit

Documentation
- Updated server-side import guidance across components, concepts, and getting-started guides to reflect the correct server module path.
- Refreshed examples in Stack Handler and Stack Provider docs for consistency with current server usage.
- Aligned permission and user onboarding examples with server-specific imports.
- Revised getting-started examples (setup and users) to use the server module.
- Updated the Supabase integration snippet to follow the server import pattern.
- No changes to public APIs or runtime behavior; examples only.

vercel · 2025-09-11T17:20:06Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
stack-backend	Ready	Preview	Comment	Sep 11, 2025 5:35pm
stack-dashboard	Ready	Preview	Comment	Sep 11, 2025 5:35pm
stack-demo	Ready	Preview	Comment	Sep 11, 2025 5:35pm
stack-docs	Ready	Preview	Comment	Sep 11, 2025 5:35pm

coderabbitai · 2025-09-11T17:20:34Z

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Caution

Review failed

The pull request is closed.

Walkthrough

Documentation examples across multiple MDX files were updated to import stackServerApp from @/stack/server instead of @/stack. Only example import paths changed; no logic, control flow, or public API declarations were modified.

Changes

Cohort / File(s)	Summary
Components docs `docs/templates/components/stack-handler.mdx`, `docs/templates/components/stack-provider.mdx`	Updated example imports to use `@/stack/server` instead of `@/stack` for `stackServerApp`; no other changes.
Concepts docs `docs/templates/concepts/permissions.mdx`, `docs/templates/concepts/user-onboarding.mdx`	Switched server-side example imports from `@/stack` to `@/stack/server` across server code blocks; content otherwise unchanged.
Getting started docs `docs/templates/getting-started/setup.mdx`, `docs/templates/getting-started/users.mdx`	Repointed example imports to `@/stack/server` in Next.js snippets and server components; no logic edits.
Other integrations `docs/templates/others/supabase.mdx`	Server action snippet now imports from `@/stack/server`; no control-flow changes.

Sequence Diagram(s)

(omitted — changes are only documentation import path edits, no runtime/control-flow changes to illustrate)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

init stack cli project-id and publishable-client-key args #888 — Updates docs to import the server app from @/stack/server, same import-path change pattern.
[Docs][site] - Add signin functionality #876 — Prior docs changes referencing @/stack that this PR aligns with by switching to the server path.

Suggested reviewers

N2D4

Poem

A rabbit hops through docs at night,
Tweaks imports till they fit just right.
From "@/stack" to server door,
Snippets match the app once more. 🐇✨

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Please see the documentation for more information.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0c4958a and 650dc1f.

📒 Files selected for processing (7)

docs/templates/components/stack-handler.mdx (1 hunks)
docs/templates/components/stack-provider.mdx (1 hunks)
docs/templates/concepts/permissions.mdx (4 hunks)
docs/templates/concepts/user-onboarding.mdx (2 hunks)
docs/templates/getting-started/setup.mdx (2 hunks)
docs/templates/getting-started/users.mdx (4 hunks)
docs/templates/others/supabase.mdx (1 hunks)

✨ Finishing touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch init-stack-more-args

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

greptile-apps

Greptile Summary

This PR modernizes the Stack Auth initialization tooling and project structure by introducing several key improvements:

Enhanced CLI Options: The init-stack package now accepts --project-id and --publishable-client-key command-line arguments, allowing users to pre-populate these critical configuration values during setup instead of manually entering them afterward. This enables automation and streamlines the developer onboarding experience.

Improved File Organization: The initialization tool now generates a cleaner project structure with separate stack/client.ts and stack/server.ts files instead of a single stack.ts file. This separation provides better organization by clearly distinguishing between client-side and server-side Stack Auth configurations, following Next.js best practices for preventing server-only code from accidentally running on the client.

Comprehensive Documentation Updates: All documentation files have been systematically updated to reflect the new file structure, with import paths changed from @/stack to @/stack/server for server-side usage and @/stack/client for client-side usage across setup guides, examples, and concept documentation.

Minor UI Refinement: The dashboard's new project page removes a redundant vertical separator between form and preview sections, likely because the different background colors already provide sufficient visual separation.

These changes integrate well with the existing codebase architecture and maintain backward compatibility while providing a more organized and automated setup experience for Stack Auth projects.

Confidence score: 4/5

This PR is safe to merge with moderate risk due to structural changes affecting many files
Score reflects comprehensive documentation updates and well-tested CLI enhancements, but file structure changes across the codebase require careful validation
Pay close attention to init-stack package changes and ensure all import path updates are consistent across the codebase

_{16 files reviewed, 6 comments}

_{Edit Code Review Bot Settings | Greptile}

greptile-apps · 2025-09-11T17:21:33Z

docs/templates/getting-started/users.mdx

@@ -33,7 +33,7 @@ Sometimes, you want to retrieve the user only if they're signed in, and redirect
 Since `useUser()` is a stateful hook, you can't use it on server components. Instead, you can import `stackServerApp` from `stack/client.ts` and call `getUser()`:


syntax: Comment mentions stack/client.ts but the actual import is from @/stack/server - this appears to be a documentation error

Suggested change

Since `useUser()` is a stateful hook, you can't use it on server components. Instead, you can import `stackServerApp` from `stack/client.ts` and call `getUser()`:

Since `useUser()` is a stateful hook, you can't use it on server components. Instead, you can import `stackServerApp` from `@/stack/server` and call `getUser()`:

BilalG1 added 7 commits September 10, 2025 11:42

init stack args

92c332a

Merge branch 'dev' into init-stack-more-args

471888c

fix imports

cf8f1bd

Merge branch 'dev' into init-stack-more-args

2ae27ce

fix docs

ac78544

fix .env

b204910

more doc fixes

27dbbc1

github-actions bot assigned BilalG1 Sep 11, 2025

Merge remote-tracking branch 'origin/dev' into init-stack-more-args

650dc1f

BilalG1 merged commit a03774f into dev Sep 11, 2025
8 of 13 checks passed

BilalG1 deleted the init-stack-more-args branch September 11, 2025 17:20

greptile-apps bot reviewed Sep 11, 2025

View reviewed changes

This was referenced Oct 15, 2025

fix convex docs #953

Merged

convex example testing #943

Merged

coderabbitai bot mentioned this pull request Nov 4, 2025

StackHandler is now a client component #988

Merged

coderabbitai bot mentioned this pull request Mar 13, 2026

change cli init across docs #1245

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Init stack more args#892

Init stack more args#892
BilalG1 merged 8 commits intodevfrom
init-stack-more-args

BilalG1 commented Sep 11, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Sep 11, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Sep 11, 2025 •

edited

Loading

Other AI code review bot(s) detected

Review failed

Uh oh!

Uh oh!

greptile-apps bot left a comment

Uh oh!

greptile-apps bot Sep 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		@@ -33,7 +33,7 @@ Sometimes, you want to retrieve the user only if they're signed in, and redirect
		Since `useUser()` is a stateful hook, you can't use it on server components. Instead, you can import `stackServerApp` from `stack/client.ts` and call `getUser()`:

Conversation

BilalG1 commented Sep 11, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

High-level PR Summary

Review by RecurseML

Summary by CodeRabbit

Uh oh!

vercel bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Other AI code review bot(s) detected

Review failed

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Greptile Summary

Confidence score: 4/5

Uh oh!

greptile-apps bot Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

BilalG1 commented Sep 11, 2025 •

edited by coderabbitai bot

Loading

vercel bot commented Sep 11, 2025 •

edited

Loading

coderabbitai bot commented Sep 11, 2025 •

edited

Loading