Skip to content

Latest commit

 

History

History
245 lines (185 loc) · 5.32 KB

getting-started.md

File metadata and controls

245 lines (185 loc) · 5.32 KB

Getting Started

This guide will help you set up and start developing with the spike.land codebase. It covers both local development and understanding the key components.

Quick Start

  1. Clone and Install
# Clone the repository
git clone https://github.com/zerdos/spike.land.git
cd spike.land

# Install dependencies
yarn install
  1. Configure Environment
# Create development variables for Cloudflare Workers
cat > .dev.vars << EOL
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
CLERK_SECRET_KEY=your_clerk_secret
EOL
  1. Start Development Environment
# Start everything (frontend + workers)
yarn dev

# Or start components individually:
yarn dev:fe      # Frontend only
yarn dev:workers # Workers only

Project Structure

spike.land/
├── packages/
│   ├── code/                 # Frontend React application
│   ├── spike.land/          # Main Cloudflare Worker
│   ├── js.spike.land/       # Transpiler Worker
│   └── spike-land-renderer/ # Renderer Worker
├── docs/                    # Documentation
└── devcontainers/          # Development containers

Key Components

Frontend Application (packages/code)

  • React 19-based UI
  • Real-time collaboration features
  • Monaco Editor integration
  • Service Worker capabilities

Main Worker (packages/spike.land)

  • Authentication and authorization
  • Real-time collaboration backend
  • Asset serving
  • AI service integration

Transpiler Worker (packages/js.spike.land)

  • Code transpilation service
  • ESBuild integration
  • Module bundling

Renderer Worker (packages/spike-land-renderer)

  • Server-side rendering
  • Screenshot/PDF generation
  • Puppeteer integration

Development Workflow

1. Local Development

# Start development servers
yarn dev

# Watch terminal output for:
- Vite development server
- Worker development output
- TypeScript compilation

2. Code Changes

  • Frontend changes hot reload automatically
  • Worker changes trigger automatic restart
  • TypeScript errors show in real-time

3. Testing Changes

# Run tests
yarn test             # All tests
yarn test:e2e        # End-to-end tests
yarn workspace @spike-npm-land/code test  # Frontend tests

4. Building

# Build everything
yarn build:all

# Build specific components
yarn build:fe      # Frontend only
yarn build:workers # Workers only

5. Deployment

# Deploy to development
yarn deploy:dev

# Deploy to production
yarn deploy:prod

Configuration Files

Frontend (packages/code)

  • vite.config.ts - Vite configuration
  • tsconfig.json - TypeScript configuration
  • tailwind.config.js - Tailwind CSS configuration

Workers

  • wrangler.toml - Cloudflare Worker configuration
  • tsconfig.json - TypeScript configuration

Development Tools

Required Tools

  • Node.js (LTS version)
  • Yarn
  • Git
  • Wrangler CLI (npm install -g wrangler)

Recommended VS Code Extensions

  • ESLint
  • Prettier
  • TypeScript and JavaScript
  • Tailwind CSS IntelliSense
  • Cloudflare Workers

Common Tasks

1. Adding a New Feature

  1. Create feature branch
git checkout -b feature/new-feature
  1. Make changes following the architecture patterns
  2. Add tests
  3. Update documentation
  4. Create pull request

2. Updating Dependencies

# Update all dependencies
yarn up

# Update specific package
yarn up package-name

3. Running Type Checks

# Check all packages
yarn types:check

# Watch mode for development
yarn workspace @spike-npm-land/code types:watch

4. Formatting Code

# Format all files
yarn fmt

# Lint check
yarn lint

Troubleshooting

Common Issues

  1. Worker Development Issues

    • Ensure Wrangler is installed and authenticated
    • Check .dev.vars configuration
    • Verify worker permissions in Cloudflare dashboard

  2. Frontend Development Issues

    • Clear Vite cache: rm -rf node_modules/.vite
    • Check for TypeScript errors: yarn types:check
    • Verify module resolution: yarn clean && yarn install

  3. Build Issues

    • Clear build artifacts: yarn clean
    • Verify all dependencies: yarn install
    • Check for TypeScript errors: yarn types:check

Getting Help

  1. Check documentation:

  2. Use development tools:

    • Chrome DevTools for frontend debugging
    • Wrangler logs for worker issues
    • TypeScript compiler output

  3. Review common patterns:

    • Component patterns in packages/code/src/@/components
    • Worker patterns in packages/spike.land/src
    • Test patterns in respective __tests__ directories

Next Steps

  1. Review the Architecture Overview
  2. Explore the Frontend Architecture
  3. Understand the Workers Architecture
  4. Learn about Data Flow
  5. Study the State Management

Contributing

See CONTRIBUTING.md for guidelines on:

  • Code style and standards
  • Pull request process
  • Testing requirements
  • Documentation updates