pack/CLAUDE.md

What is Railpack

Zero-config application builder that automatically analyzes your code and turns it into a container image. It's built on BuildKit with support for Node, Python, Go, PHP, and more.

Architecture

• CLI: Main entry point that coordinates core analysis and BuildKit execution
• Core: Analyzes apps and generates JSON build plans using language providers
• BuildKit: Converts build plans to BuildKit LLB (Low-Level Builder) format for image construction.
• Providers: Language-specific modules that detect project types (e.g. Node detects package.json) and generate appropriate build steps.
• Runtime: The built images are based on @images/debian/runtime/Dockerfile

Code style

Follow these instructions carefully when writing code:

• When writing a comment describing a function, do not start the comment with the name of the function
• Assume the person reading this code is an expert software engineer, but is not familiar with the internals of every system. Include concise one-line comments explaining key hooks, API usage, blocks of logic, etc., to help the reader quickly understand the code you've written.
• Follow Go conventions and existing patterns in the codebase
• Prefer early returns or continues to if nesting
• Use appropriate error handling with proper error wrapping
• Do not write comments that are obvious from the code itself; focus on explaining why something is done, not what it does
• Seriously, do not write comments that are obvious from the code itself.
• Do not write one-line functions
• Always use the App abstraction for file system operations.
• When configuring Mise settings, prefer TOML settings in the generated mise.toml (via AddMiseSetting) over environment variables, so users can override defaults with their own mise.toml.
• Never manually update lockfiles (yarn.lock, package-lock.json, pnpm-lock.yaml, etc.). Always use the respective package manager to generate or update lockfiles. Manual edits can result in invalid checksums and broken builds.

Workflow

• If mise is not available in your environment, install it
• Take a careful look at @mise.toml to understand what commands should be run at different points in the project lifecycle
• Do not worry about docker cache, etc. Never run docker system prune or other similar commands.
• Do not run go directly. Instead, inspect @mise.toml and use mise run <task> to run various dev lifecycle commands. For instance, you should not run go vet, go fmt, go test, etc directly.
• After making code changes, run mise run check
• Then, run unit tests (mise run test) and a couple of relevant integration tests to verify your changes.
  • Don't run tests manually using go test unless instructed to do so
  • If tests are failing that are unrelated to your changes, let me know and stop working.
• Use the cli mise task to test your changes on a specific example project, i.e. mise run cli -- --verbose build --show-plan examples/node-vite-react-router-spa/
• Run before finishing your work mise run test-update-snapshots and review the (possibly) updated snapshot files to make sure there are no unexpected changes.
• Do not run any write operations with git
• Do not use bin/railpack instead use mise run cli (which is the development build of railpack)
  • Therefore do not run mise build, we don't need a railpack binary for local testing
• Use a local tmp/ directory for temporary files instead of the global /tmp/ directory. Don't worry about cleaning up tmp directories.
• You can clone the mise repo (https://github.com/jdx/mise) into tmp/ to inspect it when needed.

Tests

There are normal unit tests, snapshot tests, and integration tests. The integration tests are most unique to this project:

• They are located in examples/ directories, and each example has a test.json and optionally a docker-compose.yml file
• They represent example projects that would be built using the railpack CLI
• CI builds and runs each example project in a distinct job to make sure railpack properly builds and runs the project
• test.json and docker-compose.yml are used to help determine what assertions should be made and what services should be run for the test
• The size.json is auto-generated and should never be manually created or updated.

Integration Tests

• Run mise run test-integration-cwd from within an examples/ directory to run the integration test for that example.
• test.json files are JSONC format and support comments. Use comments to explain temporary workarounds or special test conditions.
• In test.json we should avoid using justBuild for all but the most simple projects. justBuild does not test expectedOutput or any other assertions.
• If the project has a server component, we should use a httpCheck test. Read the @docs/src/content/docs/guides/developing-locally.md guide, specifically the ### HTTP Checks section for more information.
• httpCheck assertions assume that $PORT is respected.
• You can use "envs": { "SECRET": "123"} to add a required environment variable to a test case.

Unit tests

• Do not test log output.

Documentation

• Assume the reader knows the documentation is about Railpack. Avoid redundantly naming Railpack when the subject is clear from context.

File Conventions

• Markdown files in @docs/src/content/docs/ should be limited to 80 columns
• Do not fix indentation or formatting manually. This is corrected automatically using mise run check
• NEVER commit language-specific cache or build artifacts (e.g. Python __pycache__/, *.pyc, *.pyo files). If you encounter build artifacts that are not excluded by .gitignore, add appropriate patterns to .gitignore to exclude them