docs: project setup guide and README updates

[michellepace]

Summary

• Add project setup guide (xdocs/project-setup.md) with GitHub and Vercel configuration steps
• Restructure README with clearer sections and CI/CD workflow diagram
• Fix typos, grammar, and formatting across documentation
• Update Next.js (16.0.5) and Biome (2.3.8) dependencies

Test plan

• Verify documentation renders correctly on GitHub
• Confirm all internal links work
• Check spelling and grammar

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
nextjs-base	Ready	Preview	Comment	Nov 29, 2025 1:59pm

[coderabbitai]

Summary by CodeRabbit

Release Notes

• Documentation

  • Corrected typographical errors and standardised terminology throughout README
  • Expanded project setup guide with reorganised sections, enhanced verification workflows, and detailed procedural steps
  • Improved consistency and clarity of technical language

• Chores

  • Updated development dependencies to latest stable versions

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Documentation improvements across README and project-setup guide including typographical corrections (e.g., "setup" to "set up", "Ngork" to "Ngrok"), expanded Vitest explanation section, reorganised setup sections with clarified steps, and minor dependency version bumps for Next.js and Biome.

Changes

Cohort / File(s)	Summary
Documentation corrections and enhancements README.md, xdocs/project-setup.md	Typographical corrections ("setup" → "set up", "Ngork" → "Ngrok", "a url" → "a URL"); new explanatory section for Vitest configuration and test loading; reorganised project setup sections with expanded Vercel and E2E instructions; updated verification steps and wording refinements.
Dependency version updates package.json	Updated next from "16.0.4" to "^16.0.5" and @biomejs/biome from "^2.3.7" to "^2.3.8".

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify new Vercel and E2E setup instructions are accurate and complete
• Confirm section renumbering in project-setup.md is consistent throughout the document
• Check that dependency version bumps do not introduce incompatibilities

Possibly related PRs

• docs: add setup guide and refresh README #8: Overlapping documentation changes to README.md and xdocs/project-setup.md with similar setup and configuration content modifications.

Poem

🐰 A README hopped, now crisp and bright,
With "setup" fixed, each word just right,
From Ngork to Ngrok, typos take flight,
And Vitest dances in plain sight,
This rabbit grins—the docs delight! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarises the primary changes: documentation updates to project setup guide and README with typo/formatting fixes and dependency updates.
Description check	✅ Passed	The description clearly relates to the changeset, detailing the addition of setup documentation, README restructuring, typo fixes, and dependency updates across the files modified.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/project-setup-fixes

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6a7e389 and df2d4e5.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (3)

• README.md (3 hunks)
• package.json (1 hunks)
• xdocs/project-setup.md (5 hunks)

🧰 Additional context used

🧠 Learnings (5)

📚 Learning: 2025-11-27T10:10:31.467Z

Learnt from: CR
Repo: michellepace/nextjs-base PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-27T10:10:31.467Z
Learning: Use Biome for linting and formatting (replaces ESLint and Prettier)

Applied to files:

• package.json

📚 Learning: 2025-11-25T18:37:08.157Z

Learnt from: michellepace
Repo: michellepace/nextjs-base PR: 2
File: app/layout.tsx:76-77
Timestamp: 2025-11-25T18:37:08.157Z
Learning: The vercel/analytics and vercel/speed-insights packages have built-in environment detection in "auto" mode by default. They automatically detect development vs production environments using NODE_ENV and similar framework variables, and only send analytics data in production. They no-op during local development, so manual NODE_ENV checks are redundant.

Applied to files:

• package.json

📚 Learning: 2025-11-24T20:44:21.032Z

Learnt from: michellepace
Repo: michellepace/nextjs-base PR: 1
File: evals/actions.md:0-0
Timestamp: 2025-11-24T20:44:21.032Z
Learning: The `evals/` directory in the nextjs-base repository contains personal documentation and notes, not production code, so it doesn't require the same rigor as workflow files (e.g., placeholder references like `@<SHA>` are acceptable).

Applied to files:

• xdocs/project-setup.md

📚 Learning: 2025-11-27T09:57:56.153Z

Learnt from: michellepace
Repo: michellepace/nextjs-base PR: 6
File: app/page.tsx:21-22
Timestamp: 2025-11-27T09:57:56.153Z
Learning: In the nextjs-base repository, the maintainer prefers to keep placeholder/development text like "hello (h4)" and "no ui kit or icon library yet" in app/page.tsx rather than requiring production-ready content before merging.

Applied to files:

• xdocs/project-setup.md

📚 Learning: 2025-11-27T10:10:31.467Z

Learnt from: CR
Repo: michellepace/nextjs-base PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-27T10:10:31.467Z
Learning: Enable React Compiler for automatic optimisations in React components

Applied to files:

• README.md

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Run E2E Tests

🔇 Additional comments (8)

README.md (2)

9-9: Typo and grammar fixes look good.

The corrections—"set up" (verb form), "Ngrok" (correct spelling), and "URL" (capitalisation)—are all accurate. The addition of "(i.e. jobs!)" on line 222 improves clarity by explicitly defining what GitHub Workflows are.

Also applies to: 209-209, 222-222

---

212-220: Vitest explanation section is accurate and helpful.

The five-point explanation correctly describes the initialisation sequence and how the various configuration files work together. This is valuable documentation for developers new to the setup.

xdocs/project-setup.md (5)

5-18: Document structure and clarity are well-organised.

The reorganisation into 5 distinct parts with clear progression (Clone → Vercel → GitHub Settings → Branch Protection → CodeRabbit) makes the setup process easy to follow. The addition of explanatory blocks and checkboxes aids user understanding and progress tracking.

Also applies to: 74-127

---

7-11: GitHub CLI command is correct and includes improved transparency.

The addition of the --public flag to gh repo create is a good practice, making the new repository publicly discoverable. The command structure is correct.

---

117-127: Verification steps provide good end-to-end testing flow.

The step-by-step verification section (creating test PR, checking all status checks, verifying Vercel deployment, confirming Dependabot alerts) provides a practical way to validate the complete setup. This is a valuable addition to the guide.

---

93-99: I'm unable to complete the verification because the repository clone operation failed. Without access to the .github/workflows/ files, I cannot extract the actual job names and compare them against the documented status checks.

Status checks in branch protection configuration require manual verification against actual workflow files.

The comment asks to verify that the following documented status checks match their corresponding job names in .github/workflows/:

• Run Lint & Type Checks
• Run Unit Tests
• Run E2E Tests
• Vercel (Preview deployment)
• Run E2E Tests on Preview

Since I cannot access the repository, please verify directly by:

1. Checking the name: field for each job in your workflow files (.github/workflows/*.yml)
2. Comparing them against the list above
3. Ensuring exact matches (names are case-sensitive in GitHub branch protection)

---

19-55: Vercel and GitHub UI paths in documentation are accurate and current.

Verification against official 2025 documentation confirms both UI paths are correct:

• Vercel: Settings → Deployment Protection → "Protection Bypass for Automation" is the current path
• GitHub: Settings → Secrets and variables → Actions is the current path

No updates needed.

package.json (1)

27-27: Verify Next.js 16.0.5 and Biome 2.3.8 are available and stable.

• Biome 2.3.8: Confirmed as the latest stable release (published Nov 27, 2025); no security advisories found.
• Next.js 16.0.5: Published Nov 27, 2025 (~22 hours ago); available on jsDocs and npm mirrors but npmjs.com listing may still show 15.5.2 due to CDN propagation. While no public advisories explicitly list 16.0.5 as affected, multiple recent Next.js CVEs (CVE-2025-29927, CVE-2025-49826, etc.) are documented for earlier versions (v12–v15). Review the official Next.js security advisories to confirm this version is not impacted, especially if your app uses middleware, image optimization, or ISR.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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