porcupine

Porcupine Web

A reading management platform built with SolidJS/SolidStart. Track your reading, manage libraries, create queues, and share with friends.

Quick Start

# 1. Clone and install
git clone <repository-url>
cd porcupine-web
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your DATABASE_URL

# 3. Setup database and start
make all

App runs at http://localhost:3000

Prerequisites

• Node.js v18 or higher
• PostgreSQL (local or Docker)
• Make (optional, for convenience commands)

Tech Stack

• Framework: SolidStart v1.1.1 with SolidJS v1.9.3
• Database: PostgreSQL + Prisma ORM v6.13.0
• State: Zustand + Immer middleware
• Styling: TailwindCSS
• Auth: Session-based with HTTP-only cookies
• Testing: Vitest + Playwright

Development

Core Commands

npm run dev          # Start dev server (http://localhost:3000)
npm run build        # Production build
npm run typecheck    # TypeScript type checking
npm run validate     # Type check + lint (pre-commit check)

Database

npx prisma studio              # GUI browser (http://localhost:5555)
npx prisma migrate dev         # Run migrations
npx prisma migrate dev --name your_migration_name  # Create migration
npx prisma generate            # Regenerate client
npm run db:seed                # Seed database

Linting & Formatting

npm run lint         # Check for issues
npm run lint:fix     # Auto-fix issues
npm run format       # Format with Prettier

Testing

Test Commands

npm run test:unit              # Unit tests (Vitest)
npm run test:smoke             # Smoke tests (fast health checks)
npm run test:integration       # Integration tests (real database)
npm test                       # E2E browser tests (Playwright)

Test Database Setup

Integration tests require a separate test database:

# Create test database
createdb porcupine_test

# Add to .env
DATABASE_URL_TEST=postgresql://user@localhost:5432/porcupine_test

# Run integration tests
npm run test:integration

Test Structure

tests/
├── smoke/           # Fast component rendering checks
├── unit/            # Pure function and logic tests
├── integration/     # API routes with real database
│   └── api/         # Per-endpoint integration tests
├── e2e-api/         # Complete user flow tests
│   └── tier1-critical/  # Must-pass authentication & content flows
└── setup/           # Test utilities and database helpers
    ├── testDb.ts    # Test database client
    ├── testHelpers.ts  # Unique data generators
    └── globalSetup.ts  # Migration runner

Key files:

• tests/helpers/testData.ts - Factory functions for test data
• tests/setup/testDb.ts - Test database client and cleanup utilities
• tests/TEST_PYRAMID_PLAN.md - Overall testing strategy and architecture
• vitest.config.ts - Unit/smoke test configuration
• vitest.integration.config.ts - Integration test configuration

Project Structure

src/
├── features/        # Domain-based modules (auth, library, content, etc.)
├── routes/          # SolidStart file-based routing
│   └── api/         # API endpoints
├── shared/          # Cross-feature code
│   ├── components/  # Reusable UI
│   ├── stores/      # Zustand state (contentStore.ts)
│   ├── validation/  # Zod schemas (manual + auto-generated)
│   ├── styles/      # Tailwind patterns
│   └── utils/       # Helper functions
├── lib/             # Core utilities (db.ts, auth.ts)
└── middleware.ts    # Global authentication

Key Patterns

State Management: See src/shared/stores/contentStore.ts for Zustand + Immer pattern

Frontend Components: See .claude/skills/solidjs-dev-guidelines/SKILL.md

API Routes: See .claude/skills/solidstart-api-guidelines/SKILL.md

Testing Patterns: See .claude/skills/testing-guidelines/SKILL.md

Validation: Auto-generated from Prisma at src/shared/validation/generated/

Environment Variables

Required

DATABASE_URL="postgresql://user@localhost:5432/porcupine_db"
SESSION_SECRET="your-random-secret-string"

Optional

# Testing
DATABASE_URL_TEST="postgresql://user@localhost:5432/porcupine_test"

# Email (for password resets)
RESEND_API_KEY="your-resend-key"
FROM_EMAIL="noreply@yourdomain.com"
EMAIL_DEV_PREVIEW="true"  # Log emails instead of sending

# External APIs
GOOGLE_BOOKS_API_KEY="your-google-books-key"
GOOGLE_OAUTH_CLIENT_ID="your-oauth-client-id"
GOOGLE_OAUTH_CLIENT_SECRET="your-oauth-secret"

Docker Setup (Alternative)

cp .env.example .env
make start           # Database + Redis + dev server
make start-all       # Plus Prisma Studio + BullMQ Board
make stop            # Stop all services
make status          # Check what's running

Docker URLs:

• App: http://localhost:3000
• Prisma Studio: http://localhost:5555
• BullMQ Board: http://localhost:3001
• PostgreSQL: localhost:5433
• Redis: localhost:6379

Code Quality

Pre-commit hooks run npm run validate (typecheck + lint) on every commit.

Enhanced linting available:

npm run lint:enhanced    # All rules including stricter checks
npm run lint:security    # Security-focused rules
npm run lint:a11y        # Accessibility rules

Makefile Commands

make help       # Show all commands
make all        # Full setup (install, db, migrations, dev server)
make dev        # Start dev server
make db-studio  # Open Prisma Studio
make test       # Run tests
make lint       # Check linting
make lint-fix   # Fix linting issues
make db-reset   # Reset database (WARNING: deletes data)

Common Issues

Database connection fails: Check PostgreSQL is running and DATABASE_URL is correct

Migrations fail: Run npx prisma migrate reset to start fresh (deletes data)

Tests timeout: Ensure test database exists and DATABASE_URL_TEST is set

Type errors: Run npx prisma generate after schema changes

AI Development

For Claude Code users: See CLAUDE.md for AI-specific guidelines, restrictions, and code patterns.

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up your development environment
• Code style and conventions
• Testing requirements
• Pull request process

Community

• Code of Conduct - Our community standards
• Security Policy - How to report security issues
• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and ideas

License

This project is licensed under the MIT License - see the LICENSE file for details.

Screenshots

Home Page

Library

Profile

Queue

Search

List Dropdown

Status Dropdown

Ignore some of the google books urls in the content, from a bug that was fixed but old screenshot works

---

Built with SolidStart