Init Basics — Start Your Project Right

What is init and why use it?

Every project needs environment variables — but setting them up manually is error-prone and inconsistent.

• ›.env.example: Team template with documented placeholders (commit this!)
• ›.env: Your local secrets file (never commit this!)

The init command generates both files automatically, with variables tailored to your stack.

Three ways to initialize

Blank Mode — Start from scratch

Use when: You want minimal templates or prefer manual configuration.

evnx init
# Select: 📄 Blank (create empty .env files)

✓ Created empty .env.example
ℹ️  Tip: Run 'evnx add' to add variables interactively

Result:

# .env.example
# Add your environment variables here
# Format: KEY=value

Blueprint Mode — Pre-configured stacks (default)

Use when: You're using a common stack like Next.js, FastAPI, or Rails.

evnx init
# Select: 🔷 Blueprint (use pre-configured stack)
# Choose: T3 Turbo (Next.js + Clerk + Prisma)

📋 Preview:
  NEXTAUTH_URL=http://localhost:3000
  DATABASE_URL=postgresql://localhost:5432/app
  # ... 12 more variables

✓ Created .env.example with 15 variables

Architect Mode — Build your custom stack

Use when: You need a unique combination of language, framework, and services.

evnx init
# Select: 🏗️  Architect (build custom stack)

? Select your primary language:
❯ JavaScript / TypeScript

? Select your framework:
❯ Next.js

? Select services you'll use (Space to toggle):
❯ [Databases] PostgreSQL
❯ [Auth] Clerk
❯ [Storage] AWS S3

? Select deployment/infrastructure (optional):
❯ [Infra] Vercel

✓ Created .env.example with 18 variables

Your first init: Step-by-step

Scenario: Starting a new Next.js project

Step 1: Run init interactively

cd my-nextjs-app
evnx init

Step 2: Select Blueprint mode

? How do you want to start?
❯ 🔷 Blueprint (use pre-configured stack)

Step 3: Choose your stack

? Choose a stack blueprint:
❯ T3 Turbo (Next.js + Clerk + Prisma)
   The 2026 standard for type-safe fullstack apps.

Step 4: Preview and confirm

📋 Preview:
  NEXTAUTH_URL=http://localhost:3000
  NEXTAUTH_SECRET=CHANGE_ME
  DATABASE_URL=postgresql://localhost:5432/app
  # ... more variables

? Generate .env files with these variables? Yes

Step 5: Verify generated files

ls -la .env*
# Output:
# -rw-r--r--  .env          # Created with TODO placeholders
# -rw-r--r--  .env.example  # Created with docs + examples

cat .gitignore | grep ".env"
# Output: .env (auto-added!)

Step 6: Edit .env with real values

nano .env
# Replace:
#   NEXTAUTH_SECRET=CHANGE_ME
# With:
#   NEXTAUTH_SECRET=your_generated_secret_here

Step 7: Validate your setup

evnx validate
✓ All required variables present
✓ No placeholder values detected in .env

✅ You're done! Your project is ready for development.

Non-interactive usage for automation

Use --yes for scripting, Docker builds, or CI/CD:

# Quick start with default blueprint
evnx init --yes

# Custom output path for monorepos
evnx init --yes --path ./packages/api

# Verbose output for debugging
evnx init --yes --verbose

Common pitfalls to avoid

Skipping the preview

Always review the preview before confirming. A missing variable now saves hours of debugging later.

Overwriting existing .env files

evnx init only creates .env if it doesn't exist. To update an existing file, use evnx sync --direction reverse.

Ignoring the .gitignore update

If you manually manage .gitignore, ensure these patterns are present:

.env
.env.local
.env.*.local

Using Blank mode for complex projects

Blank mode creates empty templates. For stacks with 10+ variables, Blueprint or Architect mode saves significant time.

Next steps

Now that you've initialized your project:

1. ›Add Custom Variables — Extend your template
2. ›Sync Basics — Keep files in sync with your team
3. ›Blueprint Catalog — Explore all pre-configured stacks
4. ›Team Collaboration — Share .env.example safely