Skip to content

LOCAL_DEVELOPMENT.md

Latest commit

 

History

History
225 lines (150 loc) · 4.88 KB

LOCAL_DEVELOPMENT.md

File metadata and controls

225 lines (150 loc) · 4.88 KB
Raw

Local Development

To run Storyden locally via the repository, it's pretty easy! You can use this approach for testing, experimenting and contributing.

For full development and contribution documentation, please visit the GitHub repository.

Prerequisites

To run Storyden locally, you need to have the following installed:

  • Go - the API is written in Go!
  • Node.js - the frontend is built with Next.js
  • pnpm - the package manager for the frontend
  • Task - task runner for code generation and development workflows

If anything is missing from this list, please open an issue!

Setup Instructions

1. Clone the Repository

First, clone the repository:

git clone https://github.com/Southclaws/storyden.git
cd storyden

2. Run the Backend (Go API)

From inside the Storyden directory, you can run the API service:

go run ./cmd/backend

This will start the API server with default configuration. You'll get:

  • ./data/data.db SQLite database
  • ./data/assets to store assets (avatars, images, files, etc.)
  • A local server running at http://localhost:8000
  • OpenAPI documentation at http://localhost:8000/api/docs
  • CORS and cookie rules configured to support localhost

3. Run the Frontend (Next.js)

You can also run the frontend service:

cd web
pnpm
pnpm dev

The frontend will be available at http://localhost:3000 and will by default automatically connect to the API at http://localhost:8000.

Development Workflow

Running Tests

# Run all Go tests
go test ./...

# Run specific test package
go test ./tests/thread/...

# Run tests with verbose output
go test -v ./...

# Run end-to-end tests - automatically boots fresh backend and frontend on ports 8001/3001 then shuts them down after the tests finish
task test:e2e

Code Generation

Storyden uses heavy code generation. After modifying schemas or API specs, run:

# Regenerate everything
task generate

# Or manually:
# Generate database bindings
task generate:db

# Generate OpenAPI code (backend + frontend + docs)
task generate:openapi

Database Management

# Seed database with test data
go run ./cmd/seed

# Clean database
go run ./cmd/clean

Note: Storyden automatically handles database migrations on startup, so you don't need to run migrations manually.

Frontend Development

cd web

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Lint code
pnpm lint

# Type check
pnpm tsc --noEmit

# Regenerate API client from OpenAPI spec
pnpm openapi

Environment Variables

Create a .env file in the root directory for custom configuration:

# Database
DATABASE_URL=sqlite://data/data.db

# Server
LISTEN_ADDR=0.0.0.0:8000
PUBLIC_WEB_ADDRESS=http://localhost:3000
PUBLIC_API_ADDRESS=http://localhost:8000

# Log Level
LOG_LEVEL=debug
LOG_FORMAT=dev

# Development helpers
DEV_CHAOS_SLOW_MODE=0s
DEV_CHAOS_FAIL_RATE=0

For a full list of configuration options, see ./internal/config/config.yaml.

Troubleshooting

Port Already in Use

If port 8000 or 3000 is already in use:

# Change backend port
LISTEN_ADDR=0.0.0.0:8080 go run ./cmd/backend

# Change frontend port
cd web
PORT=3001 pnpm dev

If you change ports or need to run on different addresses, make sure to update the address configuration:

PUBLIC_WEB_ADDRESS=http://localhost:3001 \
PUBLIC_API_ADDRESS=http://localhost:8080 \
LISTEN_ADDR=0.0.0.0:8080 \
go run ./cmd/backend

These environment variables control CORS and cookie settings. See ./internal/config/config.yaml for all available configuration options.

Database Issues

If you encounter database issues, you can reset it:

rm -rf ./data/data.db
go run ./cmd/backend  # Will create fresh database
go run ./cmd/seed     # Optional: add test data

Code Generation Errors

If you see errors about missing generated files, regenerate the code:

task generate

API Testing

The OpenAPI documentation is available at:

  • Local: http://localhost:8000/api/docs
  • Interactive testing via Scalar UI

You can also use tools like:

  • Postman - import from api/openapi.yaml
  • curl - for quick testing
  • httpie - for human-friendly HTTP requests

Hot Reload

The frontend has built-in hot reload with Next.js when running pnpm dev.

Additional Resources

Getting Help

If you encounter issues:

  1. Check the documentation
  2. Search existing issues
  3. Open a new issue with details about your environment and the problem