• Package name: @gyldlab/create-next
• Create command: bun create @gyldlab/next
• Repository: gyldlab/next-app
• License: MIT

# Using npm create (like create-next-app)
npm create @gyldlab/next@latest my-app

# Using bun create
bun create @gyldlab/next my-app

# Using pnpm create
pnpm create @gyldlab/next my-app

# Using yarn create
yarn create @gyldlab/next my-app

# Create in current directory
npm create @gyldlab/next@latest .

The package manager is auto-detected from how you invoke the CLI.

# Skip prompts with template flag
npm create @gyldlab/next@latest my-app -- --template next

# Include specific add-ons
npm create @gyldlab/next@latest my-app -- --addons gsap-lenis,shadcn

# Package manager flags (override auto-detection)
npm create @gyldlab/next@latest my-app -- -b       # Use bun
npm create @gyldlab/next@latest my-app -- -p       # Use pnpm
npm create @gyldlab/next@latest my-app -- -y       # Use yarn

# Skip dependency installation
npm create @gyldlab/next@latest my-app -- --no-install

# Show detailed error traces
npm create @gyldlab/next@latest my-app -- --debug

# List available templates
npm create @gyldlab/next@latest -- templates

Note: When using npm create with flags, use -- before the flags to pass them to the CLI.

The CLI auto-detects the package manager based on how you invoke it:

Use flags to override auto-detection: -b (bun), -p (pnpm), -y (yarn).

When run without a template flag, the CLI launches an interactive mode with:

1. Animated logo - Brand display with customizable animations
2. Template selection - Use ↑/↓ to navigate, Enter to select
3. Add-on selection - Optional add-ons to enhance your project:
   • Use ↑/↓ to navigate
   • Space to toggle individual add-ons
   • 'a' to toggle all
   • Enter to continue (with selected add-ons or base only)
   • Escape to go back

You can proceed with just the base template (no add-ons) by pressing Enter without selecting any add-ons.

• shadcn - shadcn/ui component library with Tailwind CSS
• elysia - Elysia MVC backend integration with Next.js App Router
• gsap-lenis - GSAP animations + Lenis smooth scrolling

Each add-on includes pre-configured AI coding skills for enhanced development assistance.

• Uses TypeScript with strict settings for maintainable CLI code
• Uses a modular command structure so you can grow from one template to many
• Supports base templates and optional add-ons with skill integration
• Uses Bun for fast builds and testing
• Keeps templates inside this repository for versioned, auditable defaults
• Produces a dist output and bin entry that can be published to npm

Install dependencies:

bun install

Run the CLI in development mode:

bun dev -- my-app
bun dev -- my-app --template next --addons gsap-lenis -b

Disable the startup banner when needed:

GYLDLAB_CLI_NO_BANNER=1 bun dev -- my-app

Set custom banner brand text:

GYLDLAB_CLI_BRAND="YOUR BRAND" bun dev -- my-app

Set custom banner font (figlet font name):

GYLDLAB_CLI_FONT="ANSI Shadow" bun dev -- my-app

List templates:

bun dev -- templates

Build the CLI:

bun run build

Type-check, lint, test:

bun typecheck
bun lint
bun test

Run add-on smoke tests:

bun smoke:gsap-lenis   # GSAP + Lenis with skills
bun smoke:shadcn       # shadcn/ui with skills
bun smoke:elysia       # Elysia MVC with skills

Animation guide:

• See docs/ANIMATION_GUIDE.md for all banner animation settings and examples.

Link the CLI globally:

bun run build
bun link

Then test from any directory:

cd /tmp
bun create @gyldlab/next test-project
bun create @gyldlab/next test-project --template next --addons elysia,gsap-lenis -b

To publish this package to npm:

1. Build the package:

   bun run build

2. Inspect the publish payload:

npm pack --dry-run

3. Login to npm:

   npm login --scope=@gyldlab --access public

4. Publish (local/manual flow):

   npm publish --access public

5. Publish from CI with provenance (recommended):

npm publish --access public --provenance

6. Publish updates:

   # Update version in package.json first
   npm publish --access public

Security hardening: Enable npm 2FA with write protection on your maintainer account.

npm profile enable-2fa auth-and-writes

Users will then be able to run:

npm create @gyldlab/next@latest my-app
# Or with other package managers
bun create @gyldlab/next my-app
pnpm create @gyldlab/next my-app
yarn create @gyldlab/next my-app

Add base templates under templates/base/. Each base template folder should include a template.json manifest file:

{
  "id": "next",
  "name": "Your Template Name",
  "description": "Short description of when to use this template.",
  "default": true
}

Add-ons live under templates/addons/ with an addon.json manifest file:

{
  "id": "your-addon",
  "name": "Your Add-on Name",
  "description": "What this add-on provides.",
  "dependencies": {
    "some-package": "^1.0.0"
  },
  "skills": {
    "bundled": ["skill-id-1", "skill-id-2"]
  }
}

src/
  cli.ts              # Main CLI entry point
  commands/
    create.ts         # Project creation logic
    list-templates.ts # Template listing
  core/
    templates.ts      # Template/addon discovery
  ui/
    interactive.tsx   # Ink-based interactive UI
  utils/
    package-manager.ts
    project-name.ts
templates/
  base/
    next/
      template.json
      ...project files
  addons/
    shadcn/
    elysia/
    gsap-lenis/