Skip to main content

Development Setup

Set up your local development environment for Cascadia PLM.

Prerequisites​

  • Node.js 20+ (LTS recommended)
  • PostgreSQL 18+
  • Git
  • npm or pnpm

Quick Start​

1. Clone Repository​

git clone https://github.com/your-org/cascadia.git
cd cascadia/CascadiaApp

2. Install Dependencies​

npm install

3. Configure Environment​

cp .env.example .env

Edit .env with your database connection:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/cascadia
SESSION_SECRET=dev-session-secret-change-in-prod
NODE_ENV=development

4. Create Database​

Windows:

# From repository root
create-db.bat

macOS/Linux:

createdb cascadia

5. Initialize Schema​

npm run db:push

6. Seed Data (Optional)​

# Minimal seed - org, admin user, roles, program
npm run db:seed

# Comprehensive test data - multiple users, products, items
npm run db:seed:test

7. Start Development Server​

npm run dev

Access the application at http://localhost:3000

Development Commands​

CommandDescription
npm run devStart development server (port 3000)
npm run buildBuild for production
npm run servePreview production build

Database Commands​

CommandDescription
npm run db:generateGenerate migrations from schema changes
npm run db:pushPush schema directly (dev only)
npm run db:studioOpen Drizzle Studio GUI
npm run db:seedMinimal seed data
npm run db:seed:testComprehensive test data

Testing Commands​

CommandDescription
npm run testRun Vitest tests
npm run test:watchRun tests in watch mode
npm run test:coverageRun tests with coverage
npm run test:uiOpen Vitest UI
npm run test:e2eRun Playwright E2E tests
npm run test:e2e:uiRun E2E tests with UI

Code Quality​

CommandDescription
npm run lintRun ESLint
npm run formatRun Prettier
npm run checkFormat + lint fix

IDE Setup​

Install recommended extensions:

  • ESLint
  • Prettier
  • Tailwind CSS IntelliSense
  • TypeScript Vue Plugin (Volar)

Workspace settings are included in .vscode/settings.json.

WebStorm / IntelliJ​

  • Enable ESLint integration
  • Enable Prettier on save
  • Configure TypeScript to use workspace version

Project Structure​

CascadiaApp/
├── src/
│   ├── components/      # React components
│   │   ├── ui/         # Base UI components
│   │   ├── parts/      # Part-specific components
│   │   ├── documents/  # Document components
│   │   └── ...
│   ├── lib/
│   │   ├── auth/       # Authentication
│   │   ├── db/         # Database schema & queries
│   │   ├── items/      # Item type system
│   │   ├── services/   # Business logic
│   │   └── vault/      # File storage
│   ├── routes/
│   │   ├── api/        # API routes
│   │   └── ...         # UI routes
│   └── __tests__/      # Test utilities
├── tests/
│   └── e2e/            # Playwright tests
├── drizzle/            # Generated migrations
└── public/             # Static assets

Troubleshooting​

Database Connection Issues​

# Verify PostgreSQL is running
pg_isready -h localhost -p 5432

# Test connection
psql -U postgres -d cascadia -c "SELECT 1"

Port Already in Use​

# Find process using port 3000
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Kill the process or use a different port
PORT=3001 npm run dev

Node Module Issues​

# Clear and reinstall
rm -rf node_modules package-lock.json
npm install

Next Steps​