create-n8-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate McGrady
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# create-n8-app
+
+Create a new Next.js app with the N8 stack - a modern, full-stack template featuring:
+
+- **Next.js 16** - App Router, Server Components, Server Actions, Turbopack
+- **TypeScript** - Strict mode enabled
+- **Tailwind CSS v4** - Modern CSS-first configuration
+- **Shadcn/ui** - Beautiful, accessible components
+- **Drizzle ORM** - Type-safe database queries
+- **Neon** - Serverless PostgreSQL
+- **tRPC** - End-to-end type safety
+- **TanStack Query** - Powerful async state management
+- **Zustand** - Lightweight global state
+- **NextAuth.js** - Authentication with GitHub OAuth
+- **Vitest** - Fast unit testing
+- **Prettier** - Code formatting with Tailwind plugin
+
+## Usage
+
+```bash
+# With npm
+npm create n8-app@latest my-app
+
+# With pnpm
+pnpm create n8-app@latest my-app
+
+# With yarn
+yarn create n8-app my-app
+```
+
+## Options
+
+```bash
+npm create n8-app@latest my-app --skip-install  # Skip dependency installation
+npm create n8-app@latest my-app --skip-git      # Skip git initialization
+```
+
+## After Creation
+
+1. **Set up your database**
+   - Create a Neon project at [neon.tech](https://neon.tech)
+   - Copy the connection string to `.env.local`
+
+2. **Set up GitHub OAuth**
+   - Create an OAuth App at [github.com/settings/developers](https://github.com/settings/developers)
+   - Set callback URL to `http://localhost:3000/api/auth/callback/github`
+   - Copy Client ID and Secret to `.env.local`
+
+3. **Generate a secret**
+   ```bash
+   openssl rand -base64 32
+   ```
+   Add to `.env.local` as `AUTH_SECRET`
+
+4. **Run database migrations**
+   ```bash
+   pnpm db:generate
+   pnpm db:push
+   ```
+
+5. **Start developing**
+   ```bash
+   pnpm dev
+   ```
+
+## Project Structure
+
+```
+my-app/
+├── app/                    # Next.js App Router
+│   ├── api/               # API routes (tRPC, auth)
+│   ├── auth/              # Auth pages
+│   ├── globals.css        # Tailwind styles
+│   ├── layout.tsx         # Root layout
+│   ├── page.tsx           # Home page
+│   └── providers.tsx      # Client providers
+├── components/            # React components
+│   ├── auth/             # Auth components
+│   └── ui/               # Shadcn components
+├── hooks/                 # Custom React hooks
+├── lib/                   # Utility functions
+│   ├── auth.ts           # NextAuth config
+│   ├── db.ts             # Database client
+│   ├── env.ts            # Environment validation
+│   ├── trpc.ts           # tRPC client
+│   └── utils.ts          # Utilities
+├── server/                # Server-side code
+│   ├── api/              # tRPC routers
+│   └── db/               # Database schema
+├── stores/                # Zustand stores
+├── tests/                 # Test files
+├── drizzle/               # Database migrations
+└── public/                # Static assets
+```
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `pnpm dev` | Start development server with Turbopack |
+| `pnpm build` | Build for production |
+| `pnpm start` | Start production server |
+| `pnpm lint` | Run ESLint |
+| `pnpm format` | Format code with Prettier |
+| `pnpm test` | Run tests with Vitest |
+| `pnpm db:generate` | Generate Drizzle migrations |
+| `pnpm db:push` | Push schema to database |
+| `pnpm db:studio` | Open Drizzle Studio |
+
+## Development
+
+### Adding Shadcn Components
+
+```bash
+npx shadcn@latest add button
+npx shadcn@latest add card
+npx shadcn@latest add input
+```
+
+### Creating tRPC Routes
+
+Add new routers in `server/api/routers/` and register them in `server/api/root.ts`.
+
+### Using Zustand
+
+See `stores/example-store.ts` for patterns. Remember:
+- Use React Query for server data
+- Use Zustand only for client state (UI, preferences, cart)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/create-project.ts
+import fs2 from "fs-extra";
+import path2 from "path";
+import prompts from "prompts";
+import chalk2 from "chalk";
+
+// src/utils/copy-template.ts
+import fs from "fs-extra";
+import path from "path";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+async function copyTemplate(targetDir, projectName) {
+  const templateDir = path.resolve(__dirname, "..", "template");
+  if (!await fs.pathExists(templateDir)) {
+    throw new Error(`Template directory not found at: ${templateDir}`);
+  }
+  await fs.copy(templateDir, targetDir);
+  const filesToRename = [
+    { from: "_package.json", to: "package.json" },
+    { from: "_gitignore", to: ".gitignore" },
+    { from: "_env.example", to: ".env.example" },
+    { from: "_env.local", to: ".env.local" },
+    { from: "_eslintrc.json", to: ".eslintrc.json" }
+  ];
+  for (const { from, to } of filesToRename) {
+    const fromPath = path.join(targetDir, from);
+    const toPath = path.join(targetDir, to);
+    if (await fs.pathExists(fromPath)) {
+      await fs.rename(fromPath, toPath);
+    }
+  }
+  const packageJsonPath = path.join(targetDir, "package.json");
+  const packageJson = await fs.readJson(packageJsonPath);
+  packageJson.name = projectName;
+  await fs.writeJson(packageJsonPath, packageJson, { spaces: 2 });
+}
+
+// src/utils/install-deps.ts
+import { execa } from "execa";
+
+// src/utils/logger.ts
+import chalk from "chalk";
+var logger = {
+  info: (message) => {
+    console.log(chalk.blue("\u2139"), message);
+  },
+  success: (message) => {
+    console.log(chalk.green("\u2714"), message);
+  },
+  warn: (message) => {
+    console.log(chalk.yellow("\u26A0"), message);
+  },
+  error: (message) => {
+    console.log(chalk.red("\u2716"), message);
+  },
+  step: (step, total, message) => {
+    console.log(chalk.cyan(`[${step}/${total}]`), message);
+  },
+  blank: () => {
+    console.log();
+  },
+  title: (message) => {
+    console.log();
+    console.log(chalk.bold.magenta(message));
+    console.log();
+  }
+};
+
+// src/utils/install-deps.ts
+async function installDependencies(targetDir) {
+  logger.info("Installing dependencies with pnpm...");
+  try {
+    await execa("pnpm", ["install"], {
+      cwd: targetDir,
+      stdio: "inherit"
+    });
+    logger.success("Dependencies installed successfully");
+  } catch (error) {
+    logger.warn("pnpm not found, trying npm...");
+    try {
+      await execa("npm", ["install"], {
+        cwd: targetDir,
+        stdio: "inherit"
+      });
+      logger.success("Dependencies installed successfully with npm");
+    } catch {
+      throw new Error("Failed to install dependencies");
+    }
+  }
+}
+async function runShadcnInit(targetDir) {
+  logger.info("Initializing Shadcn/ui...");
+  try {
+    await execa("npx", ["shadcn@latest", "init", "-y", "-d"], {
+      cwd: targetDir,
+      stdio: "inherit"
+    });
+    logger.success("Shadcn/ui initialized successfully");
+  } catch (error) {
+    logger.warn('Shadcn/ui initialization skipped - you can run "npx shadcn@latest init" later');
+  }
+}
+
+// src/utils/git.ts
+import { execa as execa2 } from "execa";
+async function initGit(targetDir) {
+  logger.info("Initializing git repository...");
+  try {
+    await execa2("git", ["init"], {
+      cwd: targetDir,
+      stdio: "pipe"
+    });
+    await execa2("git", ["add", "-A"], {
+      cwd: targetDir,
+      stdio: "pipe"
+    });
+    await execa2("git", ["commit", "-m", "Initial commit from create-n8-app"], {
+      cwd: targetDir,
+      stdio: "pipe"
+    });
+    logger.success("Git repository initialized with initial commit");
+  } catch (error) {
+    logger.warn("Git initialization skipped - git may not be installed");
+  }
+}
+
+// src/helpers/get-package-manager.ts
+function getPackageManager() {
+  const userAgent = process.env.npm_config_user_agent || "";
+  if (userAgent.startsWith("pnpm")) {
+    return "pnpm";
+  }
+  if (userAgent.startsWith("yarn")) {
+    return "yarn";
+  }
+  if (userAgent.startsWith("bun")) {
+    return "bun";
+  }
+  return "npm";
+}
+
+// src/create-project.ts
+async function createProject(options) {
+  logger.title("\u{1F680} Create N8 App");
+  let projectName = options.projectName;
+  if (!projectName) {
+    const response = await prompts({
+      type: "text",
+      name: "projectName",
+      message: "What is your project named?",
+      initial: "my-n8-app",
+      validate: (value) => {
+        if (!value) return "Project name is required";
+        if (!/^[a-z0-9-]+$/.test(value)) {
+          return "Project name can only contain lowercase letters, numbers, and hyphens";
+        }
+        return true;
+      }
+    });
+    if (!response.projectName) {
+      logger.error("Project name is required");
+      process.exit(1);
+    }
+    projectName = response.projectName;
+  }
+  const targetDir = path2.resolve(process.cwd(), projectName);
+  if (await fs2.pathExists(targetDir)) {
+    const { overwrite } = await prompts({
+      type: "confirm",
+      name: "overwrite",
+      message: `Directory ${projectName} already exists. Overwrite?`,
+      initial: false
+    });
+    if (!overwrite) {
+      logger.error("Operation cancelled");
+      process.exit(1);
+    }
+    await fs2.remove(targetDir);
+  }
+  const totalSteps = options.skipInstall ? 2 : 4;
+  logger.step(1, totalSteps, "Creating project structure...");
+  await fs2.ensureDir(targetDir);
+  await copyTemplate(targetDir, projectName);
+  logger.success("Project structure created");
+  if (!options.skipGit) {
+    logger.step(2, totalSteps, "Initializing git...");
+    await initGit(targetDir);
+  }
+  if (!options.skipInstall) {
+    logger.step(options.skipGit ? 2 : 3, totalSteps, "Installing dependencies...");
+    await installDependencies(targetDir);
+    logger.step(options.skipGit ? 3 : 4, totalSteps, "Setting up Shadcn/ui...");
+    await runShadcnInit(targetDir);
+  }
+  const pm = getPackageManager();
+  const runCmd = pm === "npm" ? "npm run" : pm;
+  logger.blank();
+  logger.title("\u2705 Success! Your N8 app is ready.");
+  console.log(chalk2.dim("  Next steps:"));
+  console.log();
+  console.log(chalk2.cyan(`  cd ${projectName}`));
+  if (options.skipInstall) {
+    console.log(chalk2.cyan(`  ${pm} install`));
+  }
+  console.log(chalk2.cyan(`  ${runCmd} dev`));
+  console.log();
+  console.log(chalk2.dim("  Don't forget to:"));
+  console.log(chalk2.dim("  \u2022 Set up your .env.local with database and auth credentials"));
+  console.log(chalk2.dim('  \u2022 Run "pnpm drizzle-kit generate" to create migrations'));
+  console.log(chalk2.dim('  \u2022 Add Shadcn components with "npx shadcn@latest add [component]"'));
+  console.log();
+  console.log(chalk2.bold("  Happy coding! \u{1F389}"));
+  console.log();
+}
+
+// src/index.ts
+var program = new Command();
+program.name("create-n8-app").description("Create a new Next.js app with the N8 stack").version("0.1.0").argument("[project-name]", "Name of the project").option("--skip-install", "Skip installing dependencies").option("--skip-git", "Skip initializing git repository").action(async (projectName, options) => {
+  try {
+    await createProject({
+      projectName,
+      skipInstall: options.skipInstall ?? false,
+      skipGit: options.skipGit ?? false
+    });
+  } catch (error) {
+    logger.error("Failed to create project");
+    if (error instanceof Error) {
+      logger.error(error.message);
+    }
+    process.exit(1);
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "create-n8-app",
+  "version": "0.1.0",
+  "description": "Create a Next.js app with the N8 stack - Next.js 16, Tailwind v4, Shadcn/ui, Drizzle, tRPC, TanStack Query, Zustand, NextAuth, and more",
+  "type": "module",
+  "bin": {
+    "create-n8-app": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "create",
+    "nextjs",
+    "next",
+    "react",
+    "typescript",
+    "tailwind",
+    "shadcn",
+    "drizzle",
+    "trpc",
+    "tanstack-query",
+    "zustand",
+    "nextauth",
+    "starter",
+    "template",
+    "scaffold"
+  ],
+  "author": "Nate McG",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/natemcgrady/create-n8-app"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.10.0",
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "execa": "^9.5.1",
+    "fs-extra": "^11.2.0",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/_env.example

@@ -0,0 +1,34 @@
+# =============================================================================
+# N8 Stack Environment Variables
+# =============================================================================
+# Copy this file to .env.local and fill in your values
+# Never commit .env.local to version control!
+
+# =============================================================================
+# Database (Neon)
+# =============================================================================
+# Get your connection string from: https://neon.tech
+DATABASE_URL="postgresql://user:password@host/database?sslmode=require"
+
+# =============================================================================
+# Authentication (NextAuth.js / Auth.js)
+# =============================================================================
+# Generate a secret with: openssl rand -base64 32
+AUTH_SECRET="your-secret-here-at-least-32-characters"
+
+# GitHub OAuth
+# Create an OAuth App at: https://github.com/settings/developers
+# Set callback URL to: http://localhost:3000/api/auth/callback/github
+AUTH_GITHUB_ID="your-github-client-id"
+AUTH_GITHUB_SECRET="your-github-client-secret"
+
+# =============================================================================
+# Public Variables (exposed to browser)
+# =============================================================================
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+
+# =============================================================================
+# AI (Optional)
+# =============================================================================
+# Get your API key from: https://platform.openai.com
+OPENAI_API_KEY="sk-..."

package/template/_env.local

@@ -0,0 +1,31 @@
+# =============================================================================
+# N8 Stack Environment Variables
+# =============================================================================
+# Fill in your values below
+
+# =============================================================================
+# Database (Neon)
+# =============================================================================
+DATABASE_URL="postgresql://user:password@host/database?sslmode=require"
+
+# =============================================================================
+# Authentication (NextAuth.js / Auth.js)
+# =============================================================================
+AUTH_SECRET="change-me-generate-with-openssl-rand-base64-32"
+AUTH_GITHUB_ID=""
+AUTH_GITHUB_SECRET=""
+
+# =============================================================================
+# Public Variables
+# =============================================================================
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+
+# =============================================================================
+# AI (Optional)
+# =============================================================================
+# OPENAI_API_KEY=""
+
+# =============================================================================
+# Skip validation during initial setup
+# =============================================================================
+SKIP_ENV_VALIDATION="true"

package/template/_eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["next/core-web-vitals", "next/typescript"]
+}

package/template/_gitignore

@@ -0,0 +1,46 @@
+# Dependencies
+node_modules
+.pnpm-store
+
+# Next.js
+.next
+out
+
+# Production
+build
+dist
+
+# Debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Local env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Vercel
+.vercel
+
+# TypeScript
+*.tsbuildinfo
+next-env.d.ts
+
+# Testing
+coverage
+
+# IDE
+.idea
+.vscode
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Drizzle
+drizzle/*.sql

package/template/_package.json

@@ -0,0 +1,59 @@
+{
+  "name": "my-n8-app",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio"
+  },
+  "dependencies": {
+    "@auth/drizzle-adapter": "^1.7.0",
+    "@neondatabase/serverless": "^0.10.4",
+    "@tanstack/react-query": "^5.62.0",
+    "@trpc/client": "^11.0.0-rc.660",
+    "@trpc/react-query": "^11.0.0-rc.660",
+    "@trpc/server": "^11.0.0-rc.660",
+    "ai": "^4.0.0",
+    "@ai-sdk/openai": "^1.0.0",
+    "drizzle-orm": "^0.36.4",
+    "next": "^15.1.0",
+    "next-auth": "^5.0.0-beta.25",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "zod": "^3.23.8",
+    "zustand": "^5.0.2",
+    "superjson": "^2.2.2",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.6.0",
+    "lucide-react": "^0.468.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.0.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.4",
+    "drizzle-kit": "^0.28.1",
+    "jsdom": "^25.0.1",
+    "postcss": "^8.4.49",
+    "prettier": "^3.4.2",
+    "prettier-plugin-tailwindcss": "^0.6.9",
+    "tailwindcss": "^4.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "eslint": "^9.16.0",
+    "eslint-config-next": "^15.1.0"
+  }
+}

package/template/app/api/auth/[...nextauth]/route.ts

@@ -0,0 +1,3 @@
+import { handlers } from '@/lib/auth'
+
+export const { GET, POST } = handlers

package/template/app/api/trpc/[trpc]/route.ts

@@ -0,0 +1,19 @@
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch'
+import { appRouter } from '@/server/api/root'
+import { createTRPCContext } from '@/server/api/trpc'
+
+const handler = (req: Request) =>
+  fetchRequestHandler({
+    endpoint: '/api/trpc',
+    req,
+    router: appRouter,
+    createContext: () => createTRPCContext({ headers: req.headers }),
+    onError:
+      process.env.NODE_ENV === 'development'
+        ? ({ path, error }) => {
+            console.error(`❌ tRPC failed on ${path ?? '<no-path>'}: ${error.message}`)
+          }
+        : undefined,
+  })
+
+export { handler as GET, handler as POST }