Skip to content

Add project assets and update dependencies #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michellepace merged 1 commit into from
Dec 1, 2025
Merged

Add project assets and update dependencies #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
180 changes: 7 additions & 173 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,12 @@
![Next.js 16 - a modern template repo](x_docs/images/github-social-thin.jpg)
# README - Devflow

*A Next.js 16 template with modern tooling and CI/CD automation. Code quality checks (linting, formatting, type checking, testing) run via Lefthook locally and GitHub Actions on PRs. Dependency updates automated via Dependabot. Deployments handled by Vercel: Preview for PRs, Production for main. Assumes Claude Code.*

<div align="center">
<a href="x_docs/images/app_screenshot.jpg" target="_blank">
<img src="x_docs/images/app_screenshot.jpg" alt="Homepage in light and dark modes with UI library guidance" width="750">
</a>
<p><em>Template homepage with theming setup — UI component library still needed</em></p>
</div>
A community-driven platform for asking and answering programming questions. Get help, share knowledge, and collaborate with other developers from around the world.

---

## 🎯 Use This Template

1. Follow [x_docs/project-setup.md](x_docs/project-setup.md) to clone, set up GitHub, set up Vercel.

2. Install UI components like shadcn/ui

3. Replace page.tsx, layout.tsx, counter.tsx, button.tsx, theme-toggle.tsx (use an icon), globals.css, fonts.ts

## What's Installed?

For exact list see [package.json](package.json)
Next.js 16 with the below:

| Category | Tool | What it does |
| :------- | :--- | :----------- |
Expand All @@ -38,29 +23,7 @@ For exact list see [package.json](package.json)
| Analytics | [Vercel Speed Insights](https://vercel.com/docs/speed-insights) | Real user performance metrics viewable on Vercel |
| | [Vercel Web Analytics](https://vercel.com/docs/analytics) | Privacy-friendly visitor analytics viewable on Vercel |

![Explained banner](x_docs/images/explained.jpg)

## 📦 Next.js Installation Explained

This template was initialised with the following options and then updated:

```bash
# Next.js installer
$ npx create-next-app@latest

Would you like to use TypeScript? ✔️ Yes
Which linter would you like to use? ✔️ Biome
Would you like to use React Compiler? ✔️ Yes
Would you like to use Tailwind CSS? ✔️ Yes
Would you like your code inside a src/ directory? ❌ No
Would you like to use App Router? (recommended) ✔️ Yes
Would you like to customise the import alias (@/* by default)? ❌ No

# Update all dependencies to latest versions
npm outdated # Check outdated packages (2025-11-20)
npx npm-check-updates -u # Rewrite package.json with latest
npm install # Install updated versions
```
For exact list see [package.json](package.json)

## ⚙️ Config Files Explained

Expand Down Expand Up @@ -93,139 +56,10 @@ npm install # Install updated versions

---

## 🔄 CI/CD Workflow Explained

This diagram shows how CI automation integrates into a typical development workflow:

```text
┌─────────────────────────────────────────────────────────────────────────────┐
│ 💻 LAPTOP: Create a new branch (tests on local dev machine)
└─────────────────────────────────────────────────────────────────────────────┘

git checkout -b feature/add-dark-mode
│
├─ Commit 1: Add light/dark mode ⚡ pre-commit hook runs (3s)
│ ├─ 🎨 Biome lint and format ✅ Auto-fixed & staged
│ ├─ 🔍 TypeScript type check ✅ Pass
│ └─ 🧪 Vitest unit tests ✅ Pass
│ (then committed on all pass)
│
├─ Commit 2: (some more work here) ⚡ pre-commit hook runs again
│
└─ Commit 3: (some more work here) ⚡ pre-commit hook runs again

git push origin feature/add-dark-mode ⚡ pre-PUSH hook runs
└─ 🎭 Playwright E2E tests ✅ Pass (then pushed to GH)

┌─────────────────────────────────────────────────────────────────────────────┐
│ ☁️ GITHUB: Workflows kickoff on GitHub machines when PR is created
└─────────────────────────────────────────────────────────────────────────────┘

Create Pull Request → GitHub Actions triggered automatically
│
├─ 🤖 Workflow 1: Lint & Type (biome, tsc)
│ ├─ Checkout code
│ ├─ Setup Node.js LTS
│ ├─ Install dependencies (npm ci)
│ ├─ Run Biome checks ✅ Pass
│ └─ Run TypeScript checks ✅ Pass
│
├─ 🤖 Workflow 2: Unit Tests (vitest)
│ ├─ Checkout code
│ ├─ Setup Node.js LTS
│ ├─ Install dependencies (npm ci)
│ └─ Run Vitest tests ✅ Pass
│
└─ 🤖 Workflow 3: E2E Tests (playwright)
├─ Checkout code
├─ Setup Node.js LTS
├─ Install dependencies (npm ci)
├─ Install Playwright browsers
├─ Build Next.js production
└─ Run Playwright tests ✅ Pass

── Meanwhile, Vercel deploys Preview ──────────────────────────

🚀 Vercel: Preview deployment ready
└─ Sends repository_dispatch event to GitHub

└─ 🤖 Workflow 4: E2E Tests on Vercel Preview
├─ Triggered by Vercel (not PR event)
├─ Runs Playwright against live Preview URL
└─ Tests real Vercel deployment ✅ Pass

GITHUB PR Status: ✅ All checks passed

🐰 CodeRabbit AI Review Complete
└─ 3 nitpick comments posted:
├─ "Consider using const instead of let" (Button.tsx:12)
├─ "Add JSDoc comment" (ThemeContext.tsx:8)
└─ "Extract magic string to constant" (utils.ts:45)

┌─────────────────────────────────────────────────────────────────────────────┐
│ 💻 Back to Laptop (Addressing 1 out of 3 nitpick comments on open PR)
└─────────────────────────────────────────────────────────────────────────────┘

├─ Commit 4: Use const instead of let ⚡ pre-commit hook runs

git push origin feature/add-dark-mode ⚡ pre-push hook runs
└─ 🎭 Playwright E2E tests ✅ Pass (then pushed to GH)

┌─────────────────────────────────────────────────────────────────────────────┐
│ ☁️ GITHUB (Workflows kick off again on any PR changes)
└─────────────────────────────────────────────────────────────────────────────┘

New commits pushed → GitHub Actions re-run automatically
│
├─ 🤖 Lint & Type ✅ Pass
├─ 🤖 Unit Tests ✅ Pass
└─ 🤖 E2E Tests ✅ Pass

PR Status: ✅ All checks passed (1 new commit)
🐰 CodeRabbit: "Looks good! 1 issue resolved."

Okay I'm ready! [Merge Pull Request] ← Click! 🎉

┌─────────────────────────────────────────────┐
│ Branch Protection Verified: │
│ ✅ All status checks passed │
│ ✅ Branch is up to date with main │
└─────────────────────────────────────────────┘

main branch updated (merge commit preserves 4 commits)
└─ 🚀 Vercel deployment triggered → Production
```

Key CI Takeaways

- Local Hooks — Catch issues before commit or reaching GitHub
- GitHub Actions — Validate every PR with fresh environment (reproducible CI)
- Branch Protection — Prevents merging broken code (all checks must pass)
- Fast Feedback — Pre-commit catches 90% of issues locally in ~3s vs ~2min CI wait
- Quality Gates — Code is validated 2× (local + CI) before reaching production

![Quick rough notes](x_docs/images/rough.jpg)

## 📝 Quick Notes

(1) Use Ngrok to Test App From Phone

```markdown
1. Sign up and follow https://dashboard.ngrok.com/get-started/setup/linux
2. Then: (Terminal 1: `npm run dev`) + (Terminal 2: `ngrok http 3000`)
3. Ngrok gives a URL to connect from phone (shareable)
```

(2) How Vitest Pieces Work Together

```markdown
1. When you run npm test, Vitest loads vitest.config.ts
2. The config tells Vitest to use jsdom and load `vitest.setup.ts`
3. Your test files can use global test functions and extended matchers
4. The @/* import alias works in tests thanks to `vite-tsconfig-paths`
5. React components are compiled with React Compiler (matching prod)
```
(1) Use Ngrok to Test App From Phone: (Terminal 1: `npm run dev`) + (Terminal 2: `ngrok http 3000`)

(3) GitHub - A branch protection ruleset to be setup to protect main. Incldues checks for GitHub workflow jobs to pass before merging PR to main. See [x_docs/project-setup.md](x_docs/project-setup.md).
(2) GitHub Action - A branch protection ruleset exists to protect main. Incldues checks for GitHub workflow jobs to pass before merging PR to main. See [x_docs/project-setup.md](x_docs/project-setup.md) for config details.

(4) Vercel For Deploys - When you raise a PR it automatically deploys to Vercel Preview and Playwright e2e tests run on that too in addition to GitHub servers. When you merge the PR into main, you are deploying to Vercel prod. See [x_docs/project-setup.md](x_docs/project-setup.md).
(3) Vercel For Deploys - When you raise a PR it automatically deploys to Vercel Preview and Playwright e2e tests run on that too in addition to GitHub servers. When you merge the PR into main, you are deploying to Vercel prod. See [x_docs/project-setup.md](x_docs/project-setup.md) for config details.
11 changes: 9 additions & 2 deletions biome.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"$schema": "https://biomejs.dev/schemas/2.3.7/schema.json",
"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
"vcs": {
"enabled": true,
"clientKind": "git",
Expand All @@ -8,7 +8,14 @@
},
"files": {
"ignoreUnknown": true,
"includes": ["**", "!node_modules", "!.next", "!dist", "!build"]
"includes": [
"**",
"!node_modules",
"!.next",
"!dist",
"!build",
"!x_docs/reference"
]
},
"css": {
"parser": {
Expand Down
Loading
Loading