create-insforge-app

Scaffold a new React, Next.js, or React Router application with modern tooling and best practices.

Usage

Create a new project with a specific name:

npx create-insforge-app my-project

Or specify the framework directly:

npx create-insforge-app my-project --frame react

The CLI also supports environment variable injection:

npx create-insforge-app my-project --frame react --base-url https://api.example.com --anon-key your_key_here

The project will be created in a new directory named after your project.

Options

• [project-name] - Name of the project (optional, will prompt if not provided)
• -f, --frame <framework> - Framework to use (react, nextjs, react-router)
• --base-url <url> - Base URL for your backend API (optional, will be written to .env)
• --anon-key <key> - Anonymous key (optional, will be written to .env)
• --skip-install - Skip automatic dependency installation

Interactive Mode

If you don't provide all options, the CLI will prompt you:

npx create-insforge-app
# ? Project name: (My First InsForge App)
# ? Select a framework:
#   > React + Vite
#     Next.js
#     React + Vite + React Router

What's Included

Each template includes:

React (Vite)

• React 19.2.0 with TypeScript
• Vite 7 (Rolldown) for lightning-fast development
• Tailwind CSS 3.4.15 pre-configured
• Modern ESLint flat config
• TypeScript project references
• Ready for production

Next.js

• Next.js 15.5.6 with App Router
• React 19.0.0 with TypeScript
• Tailwind CSS 3.4.17 pre-configured
• Server-side rendering support
• Optimized for performance
• Vercel deployment ready

React Router (Vite)

• React 19.2.0 with TypeScript
• React Router 7.3.0 for client-side routing
• Vite 7 (Rolldown) for fast development
• Tailwind CSS 3.4.15 pre-configured
• Example routes and layout
• Multiple pages (Home, About)

After Creating Your Project

1. Navigate to your project:

cd my-project

2. Install dependencies (if you used --skip-install):

npm install

3. Start the development server:

npm run dev

Environment Variables

The templates include environment variable support. Create a .env file (React/React Router) or .env.local file (Next.js) with your configuration:

React and React Router

VITE_INSFORGE_BASE_URL=https://your-app.region.insforge.app
VITE_INSFORGE_ANON_KEY=your_insforge_anon_key_here

Next.js

NEXT_PUBLIC_INSFORGE_BASE_URL=https://your-app.region.insforge.app
NEXT_PUBLIC_INSFORGE_ANON_KEY=your_insforge_anon_key_here

Note: You can inject these values during project creation using --base-url and --anon-key flags.

Features

• 🚀 Fast project scaffolding
• 📦 Modern, up-to-date dependencies
• 🎨 Tailwind CSS pre-configured in all templates
• 📝 TypeScript support with strict mode
• 🔧 ESLint configured with latest flat config
• ⚡ Vite 7 with Rolldown for React templates
• 🎯 Framework-specific best practices
• 🌍 Environment variable support

Available Scripts

All templates include the following scripts:

• npm run dev - Start development server
• npm run build - Build for production
• npm run lint - Run ESLint
• npm run preview - Preview production build (Vite templates only)
• npm start - Start production server (Next.js only)

Troubleshooting

Environment Variables Not Working

• Ensure the file is named .env (React/React Router) or .env.local (Next.js)
• Restart the dev server after changing env variables
• For Vite apps, variables must start with VITE_
• For Next.js, public variables must start with NEXT_PUBLIC_

Dependencies Installation Failed

If automatic installation fails:

cd my-project
rm -rf node_modules package-lock.json
npm install

Port Already in Use

If the default port is in use:

• React/React Router: The dev server will automatically try the next available port
• Next.js: Change the port with npm run dev -- -p 3001

Project Structure

React Template

my-project/
├── src/
│   ├── App.tsx           # Main application component
│   ├── App.css           # App styles
│   ├── main.tsx          # Application entry point
│   ├── index.css         # Global styles with Tailwind
│   └── assets/           # Static assets
├── public/               # Public static files
├── index.html            # HTML template
├── package.json
├── tsconfig.json
├── vite.config.ts
└── tailwind.config.js

React Router Template

my-project/
├── src/
│   ├── App.tsx           # Router configuration
│   ├── main.tsx          # Application entry point
│   ├── index.css         # Global styles with Tailwind
│   ├── components/
│   │   └── Layout.tsx    # Layout with navigation
│   └── pages/
│       ├── Home.tsx      # Home page
│       └── About.tsx     # About page
├── public/
├── index.html
├── package.json
└── vite.config.ts

Next.js Template

my-project/
├── src/
│   └── app/
│       ├── layout.tsx    # Root layout
│       ├── page.tsx      # Home page
│       └── globals.css   # Global styles with Tailwind
├── public/
├── next.config.ts
├── package.json
└── tsconfig.json

Learn More

• React Documentation
• Next.js Documentation
• React Router Documentation
• Vite Documentation
• Tailwind CSS Documentation

License

MIT