Setting Up Your Environment

Let's configure your development environment for RANA development. This lesson covers installation, configuration, and verification.

Prerequisites

• Node.js 18.0 or higher
• npm 9.0+ or pnpm 8.0+
• An API key from at least one LLM provider
• A code editor (VS Code recommended)

Step 1: Create a New Project

The fastest way to start is with create-rana-app:

npx create-rana-app my-ai-app
cd my-ai-app

This creates a new project with:

• Next.js 14 with App Router
• TypeScript configuration
• RANA packages pre-installed
• Example chat component
• API route template
• Environment file template

Step 2: Configure API Keys

Copy the environment template and add your API keys:

cp .env.example .env.local

Edit .env.local with your keys:

# .env.local

# Choose at least one provider
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...

# Optional: Default model
RANA_DEFAULT_MODEL=claude-sonnet-4-20250514

Step 3: Verify Installation

Run the doctor command to verify everything is configured correctly:

npx rana doctor

You should see output like:

✓ Node.js version: 20.10.0
✓ npm version: 10.2.3
✓ @rana/core: 1.0.0
✓ @rana/react: 1.0.0
✓ @rana/prompts: 1.0.0
✓ ANTHROPIC_API_KEY: configured
✓ TypeScript: configured
✓ Next.js: configured

All checks passed! Your environment is ready.

Step 4: Start Development Server

npm run dev

Open http://localhost:3000 to see the example chat application.

Project Structure

Your new project has this structure:

my-ai-app/
├── app/
│   ├── api/
│   │   └── chat/
│   │       └── route.ts    # Chat API endpoint
│   ├── page.tsx            # Home page with chat
│   └── layout.tsx          # Root layout
├── components/
│   └── Chat.tsx            # Chat component
├── lib/
│   └── agent.ts            # Agent configuration
├── .env.example            # Environment template
├── .env.local              # Your API keys (git-ignored)
├── package.json
├── tsconfig.json
└── next.config.js

VS Code Setup (Recommended)

For the best development experience, install these VS Code extensions:

• TypeScript - Built-in, ensure it's enabled
• ESLint - For code linting
• Prettier - For code formatting
• Tailwind CSS IntelliSense - For styling

Add these settings to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.tsdk": "node_modules/typescript/lib"
}

Troubleshooting

API Key Not Working

• Check for extra spaces or quotes in .env.local
• Verify the key is valid in your provider's dashboard
• Restart the dev server after changing .env.local

Module Not Found Errors

rm -rf node_modules package-lock.json
npm install

TypeScript Errors

• Ensure TypeScript 5.0+ is installed
• Restart VS Code TypeScript server (Cmd/Ctrl+Shift+P → Restart TS Server)

Checklist

What's Next?

Your environment is ready! In the next lesson, we'll build your first RANA project from scratch to understand all the pieces.