@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/monorepo-patterns.md

@@ -0,0 +1,287 @@
+---
+name: monorepo-patterns
+description: Structure monorepos with Turborepo — workspace dependencies, shared packages, build caching, and task pipelines.
+---
+
+# Monorepo Patterns
+
+## When to Use
+
+Use a monorepo when you have multiple packages or apps that share code,
+configuration, or release cycles. A monorepo eliminates version drift between
+packages, simplifies cross-cutting refactors, and enables atomic commits across
+your entire system. These patterns focus on Turborepo with npm/pnpm workspaces.
+
+## How It Works
+
+### 1. Workspace Structure
+
+```
+monorepo/
+  apps/
+    web/              ← Next.js frontend
+    api/              ← Express API server
+    cli/              ← CLI tool
+    docs/             ← Documentation site
+  packages/
+    ui/               ← Shared React components
+    core/             ← Auth, API client, config
+    tsconfig/         ← Shared TypeScript configs
+    eslint-config/    ← Shared ESLint configs
+  turbo.json
+  package.json
+```
+
+Root `package.json`:
+
+```json
+{
+  "private": true,
+  "workspaces": ["apps/*", "packages/*"],
+  "devDependencies": {
+    "turbo": "^2.0.0"
+  }
+}
+```
+
+### 2. Workspace Dependencies
+
+Reference internal packages by name. No `file:` or `link:` prefixes needed
+with modern workspaces.
+
+```json
+// apps/web/package.json
+{
+  "name": "@myorg/web",
+  "dependencies": {
+    "@myorg/ui": "workspace:*",
+    "@myorg/core": "workspace:*"
+  }
+}
+```
+
+```json
+// packages/ui/package.json
+{
+  "name": "@myorg/ui",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+    "./button": { "import": "./dist/button.js", "types": "./dist/button.d.ts" }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
+  }
+}
+```
+
+### 3. Shared TypeScript Config
+
+```json
+// packages/tsconfig/base.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+
+// packages/tsconfig/nextjs.json
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "module": "ESNext",
+    "plugins": [{ "name": "next" }]
+  }
+}
+```
+
+Apps extend the shared config:
+
+```json
+// apps/web/tsconfig.json
+{
+  "extends": "@myorg/tsconfig/nextjs.json",
+  "include": ["src", "next-env.d.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+### 4. Turborepo Task Pipeline
+
+```json
+// turbo.json
+{
+  "$schema": "https://turbo.build/schema.json",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**"],
+      "env": ["NODE_ENV"]
+    },
+    "dev": {
+      "dependsOn": ["^build"],
+      "cache": false,
+      "persistent": true
+    },
+    "test": {
+      "dependsOn": ["^build"],
+      "outputs": ["coverage/**"],
+      "env": ["CI"]
+    },
+    "lint": {
+      "dependsOn": ["^build"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"]
+    }
+  }
+}
+```
+
+`^build` means: build all dependencies first. Turbo automatically determines
+the correct order from workspace dependency graph.
+
+### 5. Build Caching
+
+Turbo caches task outputs based on file inputs, environment variables, and
+dependency graph. Unchanged packages skip rebuilding.
+
+```bash
+# First run: builds everything (~60s)
+turbo run build
+
+# Second run: all cached (~1s)
+turbo run build
+
+# After changing packages/ui: rebuilds ui + apps that depend on it
+turbo run build
+```
+
+Remote caching shares build artifacts across CI and developers:
+
+```bash
+# Enable remote cache (Vercel)
+npx turbo login
+npx turbo link
+
+# CI: use remote cache
+TURBO_TOKEN=${{ secrets.TURBO_TOKEN }} turbo run build
+```
+
+### 6. Filtering — Run Tasks for Specific Packages
+
+```bash
+# Build only the web app and its dependencies
+turbo run build --filter=@myorg/web...
+
+# Test only packages that changed since main
+turbo run test --filter=...[main]
+
+# Run dev for web + all its dependencies
+turbo run dev --filter=@myorg/web...
+
+# Build only packages in the packages/ directory
+turbo run build --filter='./packages/*'
+```
+
+### 7. Shared ESLint Config
+
+```javascript
+// packages/eslint-config/base.js
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier',
+  ],
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+  },
+};
+
+// packages/eslint-config/react.js
+module.exports = {
+  extends: ['./base.js', 'plugin:react/recommended', 'plugin:react-hooks/recommended'],
+  settings: { react: { version: 'detect' } },
+};
+```
+
+### 8. Publishing from a Monorepo
+
+Use changesets for versioning and publishing.
+
+```bash
+# Add a changeset when making changes
+npx changeset
+
+# Version packages (bumps versions, updates changelogs)
+npx changeset version
+
+# Publish changed packages
+npx changeset publish
+```
+
+```json
+// .changeset/config.json
+{
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch"
+}
+```
+
+### 9. Common Scripts
+
+```json
+// Root package.json
+{
+  "scripts": {
+    "dev": "turbo run dev",
+    "build": "turbo run build",
+    "test": "turbo run test",
+    "lint": "turbo run lint",
+    "typecheck": "turbo run typecheck",
+    "clean": "turbo run clean && rm -rf node_modules",
+    "format": "prettier --write \"**/*.{ts,tsx,md,json}\""
+  }
+}
+```
+
+## Examples
+
+| Need | Command |
+|------|---------|
+| Build everything | `turbo run build` |
+| Dev mode for web + deps | `turbo run dev --filter=@myorg/web...` |
+| Test changed packages | `turbo run test --filter=...[main]` |
+| Add shared dependency | `npm install zod -w packages/core` |
+| Add devDependency to root | `npm install -D prettier -w .` |
+
+## Checklist
+
+- [ ] Workspace packages use `workspace:*` for internal dependencies
+- [ ] Shared configs (tsconfig, eslint, prettier) live in `packages/`
+- [ ] `turbo.json` defines task dependencies with `^build` for correct ordering
+- [ ] Build outputs are listed in `turbo.json` for proper caching
+- [ ] Remote caching is enabled for CI (Vercel or self-hosted)
+- [ ] `--filter` is used in CI to only build/test affected packages
+- [ ] Each package has its own `build`, `test`, and `lint` scripts
+- [ ] Changesets manage versioning for published packages
+- [ ] Root `package.json` is `"private": true` and only contains workspace scripts

package/assets/skills/nextjs-app-router.md

@@ -0,0 +1,237 @@
+---
+name: nextjs-app-router
+description: Leverage Next.js App Router features — server components, streaming, parallel routes, and server actions.
+---
+
+# Next.js App Router Patterns
+
+## When to Use
+
+Use these patterns when building Next.js 13+ applications with the App Router.
+Server components, streaming, and server actions fundamentally change how you
+structure data fetching, layouts, and mutations compared to the Pages Router.
+
+## How It Works
+
+### 1. Server Components by Default
+
+Every component in `app/` is a server component unless you add `'use client'`.
+Keep the client boundary as low as possible.
+
+```
+app/
+  dashboard/
+    page.tsx          ← server component (fetches data directly)
+    _components/
+      chart.tsx       ← 'use client' (needs browser APIs)
+      stats-card.tsx  ← server component (static render)
+```
+
+```tsx
+// app/dashboard/page.tsx — no 'use client', runs on the server
+import { db } from '@/lib/db';
+
+export default async function DashboardPage() {
+  const stats = await db.stats.findMany(); // direct DB access, no API route
+  return (
+    <div>
+      <StatsCard data={stats} />
+      <Chart data={stats} />  {/* client component for interactivity */}
+    </div>
+  );
+}
+```
+
+Rule: if it doesn't need `useState`, `useEffect`, event handlers, or browser
+APIs, it stays a server component.
+
+### 2. Loading and Error UI
+
+Place `loading.tsx` and `error.tsx` alongside `page.tsx` for automatic Suspense
+and error boundary wrapping.
+
+```tsx
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return <DashboardSkeleton />;
+}
+
+// app/dashboard/error.tsx
+'use client'; // error.tsx must be a client component
+
+export default function Error({ error, reset }: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div role="alert">
+      <h2>Something went wrong</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+Also use `not-found.tsx` with `notFound()` from `next/navigation` for 404 pages.
+
+### 3. Parallel Routes
+
+Render multiple pages in the same layout simultaneously using named slots.
+
+```
+app/
+  @analytics/
+    page.tsx
+    loading.tsx
+  @activity/
+    page.tsx
+    loading.tsx
+  layout.tsx
+  page.tsx
+```
+
+```tsx
+// app/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  activity,
+}: {
+  children: ReactNode;
+  analytics: ReactNode;
+  activity: ReactNode;
+}) {
+  return (
+    <div className="grid grid-cols-3">
+      <main className="col-span-2">{children}</main>
+      <aside>
+        {analytics}
+        {activity}
+      </aside>
+    </div>
+  );
+}
+```
+
+Each slot streams independently — fast panels appear first, slow panels show
+their own loading state.
+
+### 4. Intercepting Routes
+
+Show a modal on soft navigation while keeping the full page accessible via
+direct URL.
+
+```
+app/
+  photos/
+    [id]/
+      page.tsx          ← full page (direct URL or hard refresh)
+  @modal/
+    (.)photos/[id]/
+      page.tsx          ← intercepted modal (soft navigation)
+    default.tsx         ← returns null when no modal is active
+  layout.tsx
+```
+
+The `(.)` prefix intercepts one level up. Use `(..)` for two levels, `(...)` for root.
+
+### 5. Server Actions
+
+Mutate data without API routes. Define with `'use server'` and use in forms or
+call from client components.
+
+```tsx
+// app/actions/user.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import { db } from '@/lib/db';
+import { z } from 'zod';
+
+const UpdateProfileSchema = z.object({
+  name: z.string().min(1).max(100),
+  bio: z.string().max(500),
+});
+
+export async function updateProfile(formData: FormData) {
+  const parsed = UpdateProfileSchema.safeParse({
+    name: formData.get('name'),
+    bio: formData.get('bio'),
+  });
+
+  if (!parsed.success) {
+    return { error: parsed.error.flatten().fieldErrors };
+  }
+
+  await db.user.update({ where: { id: getCurrentUserId() }, data: parsed.data });
+  revalidatePath('/profile');
+}
+```
+
+```tsx
+// app/profile/edit/page.tsx
+import { updateProfile } from '@/app/actions/user';
+
+export default function EditProfile() {
+  return (
+    <form action={updateProfile}>
+      <input name="name" required />
+      <textarea name="bio" />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+### 6. Metadata and SEO
+
+```tsx
+// app/blog/[slug]/page.tsx
+import type { Metadata } from 'next';
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const post = await getPost(params.slug);
+  return {
+    title: post.title,
+    description: post.excerpt,
+    openGraph: { images: [post.coverImage] },
+  };
+}
+```
+
+### 7. Route Groups for Organization
+
+Use `(groupName)` folders to organize without affecting URLs.
+
+```
+app/
+  (marketing)/
+    about/page.tsx      → /about
+    pricing/page.tsx    → /pricing
+    layout.tsx          ← shared marketing layout
+  (dashboard)/
+    settings/page.tsx   → /settings
+    layout.tsx          ← shared dashboard layout (with sidebar)
+```
+
+## Examples
+
+| Need | Pattern | File |
+|------|---------|------|
+| Loading skeleton | `loading.tsx` | Auto-wrapped Suspense boundary |
+| Error recovery | `error.tsx` + `reset()` | Auto-wrapped error boundary |
+| Side-by-side panels | Parallel routes (`@slot`) | Independent streaming |
+| Modal over list | Intercepting routes `(.)` | Modal on click, full page on refresh |
+| Form mutation | Server action | No API route, automatic revalidation |
+
+## Checklist
+
+- [ ] Components default to server — `'use client'` only where browser APIs are needed
+- [ ] Every route segment with async data has a `loading.tsx`
+- [ ] Every route segment has an `error.tsx` with a retry button
+- [ ] Server actions validate input with Zod before touching the database
+- [ ] `revalidatePath` or `revalidateTag` is called after every mutation
+- [ ] Metadata is generated dynamically for pages with variable content
+- [ ] Route groups separate marketing pages from authenticated dashboard
+- [ ] No `fetch` calls to your own API routes from server components — query the DB directly