Document: 04-development-environment.md
Version: 1.0.0

Purpose

This document defines the standard development environment used for all Rundown projects.

Maintaining a consistent development environment across all team members reduces setup issues, improves collaboration, and ensures projects behave consistently from local development through production deployment.

Unless otherwise specified, every developer working on Rundown projects should follow these standards.

Operating System

Recommended

• Ubuntu LTS

• macOS

Supported

• Windows 11 using WSL2

The development environment should closely match the Linux-based production servers used by Rundown.

Code Editor

Standard Editor

Visual Studio Code

Alternative editors such as Cursor may be used provided they support the same development workflow.

Required Features

• Integrated Terminal

• Git Integration

• TypeScript Support

• Debugging Tools

• Extension Support

AI-Assisted Development

AI tools are considered part of the development workflow.

Recommended tools include:

• Cursor

• GitHub Copilot

• ChatGPT

Developers remain responsible for reviewing all generated code before it is committed.

AI-generated code should follow Rundown's coding standards and engineering principles.

Runtime

Node.js

Use the current active Long-Term Support (LTS) version.

Node Version Manager (nvm) is recommended to manage Node.js versions across projects.

Package Manager

The standard package manager is:

pnpm

Why pnpm?

• Faster installations

• Efficient disk usage

• Better dependency management

• Consistent lock files

Every project should include a pnpm-lock.yaml file.

Version Control

Git is required for every project.

Repositories are hosted on GitHub.

Every developer should configure:

• Name

• Email

• SSH authentication

Database

Local development should use PostgreSQL.

Each project should maintain an isolated local database.

Sample naming convention:

clientname_dev

Production databases must never be used for local development.

Environment Variables

Every project should use a .env.local file for local configuration.

Sensitive information must never be committed to version control.

Examples include:

• API Keys

• Database Credentials

• Authentication Secrets

• SMTP Credentials

• Cloud Storage Keys

Each repository should include a .env.example file containing the required variables without sensitive values.

Containerization

Docker should be used whenever practical to provide consistent development and deployment environments.

Where Docker is not required during local development, the production deployment should still remain containerized.

Code Formatting

Every project should include automated formatting tools.

Required:

• Prettier

Recommended:

• ESLint

Formatting should be automated wherever possible rather than enforced manually.

Project Configuration

Every new project should include:

• TypeScript

• ESLint

• Prettier

• Git Repository

• README

• Environment Example File

• License (if applicable)

Browser Support

Development should include testing on modern browsers.

Minimum supported browsers:

• Chrome

• Edge

• Firefox

• Safari

Additional browser testing should be performed when required by project specifications.

Local Testing

Before committing code, developers should verify:

• Application starts successfully.

• Build completes without errors.

• No TypeScript errors.

• No linting errors.

• Primary user flows function correctly.

Development Workflow

The standard local development workflow is:

1. Clone the repository.

2. Install dependencies.

3. Configure environment variables.

4. Start local services.

5. Run the development server.

6. Create a feature branch.

7. Develop and test locally.

8. Commit changes.

9. Push to GitHub.

10. Open a Pull Request.

Detailed Git procedures are documented separately.

Required Software

Every Rundown developer should have the following installed:

Summary

A standardized development environment ensures every Rundown project begins with a consistent foundation.

Reducing differences between local and production environments improves reliability, simplifies onboarding, and minimizes deployment issues.