• Getting Started
  • Installing Manually
    • Building Static Assets
    • Installing on macOS
  • Running Tests
    • Running Tests with Docker Compose
    • Running Playwright (E2E) Tests
      • Running with Docker Compose
      • Running Locally
  • Running the App
    • Running with Docker Compose
    • Running Locally
  • Linting and Tidying with Precious
    • Running via Docker
    • Running Locally
    • Pre-commit Hook
  • Local Configuration Changes
  • Compatibility Notes

Getting Started

We strongly recommend using metacpan-docker. This will give you a virtual machine already configured and ready to start developing on.

If you prefer not to use Docker, the following commands will get you started:

Installing Manually

carton install
npm install
export PATH="$(realpath ./node_modules/.bin):$PATH"

Building Static Assets

npm run build

Without running this command you may get errors about a missing "asset map".

Installing on macOS

If you like, you can install carton and cmark via Homebrew:

brew install carton cmark

On an ARM Mac you may need to install CommonMark in the following way:

LIBRARY_PATH=/opt/homebrew/lib CPATH=/opt/homebrew/include cpm install -g CommonMark

If your carton install is having issues with SSL-related modules, you may need to use an OPENSSL_PREFIX. Something like:

OPENSSL_PREFIX="/usr/local/Cellar/openssl@1.1/1.1.1q" carton install

You may need to check /usr/local/Cellar/openssl@1.1 to find the latest installed path on your system.

Running Tests

You can use the supplied wrapper around prove to run tests:

./bin/prove t

To run the tests in parallel, add -j8 (or however many CPUs you have) to the prove command.

Running Tests with Docker Compose

Run all tests using the test profile:

docker compose --profile test run --rm test

Run an arbitrary command:

docker compose --profile test run --rm test prove -lvr t/controller/search.t

Running Playwright (E2E) Tests

Playwright tests live in the e2e/ directory.

Running with Docker Compose

docker compose --profile test run --rm playwright

Running Locally

npm test

This automatically starts a local server on port 5099 (via plackup) before running the tests. If a server is already running on that port, it will be reused.

To run the tests against a server you've already started on a different port:

PLAYWRIGHT_PORT=5001 npm test

When PLAYWRIGHT_PORT is set, Playwright skips starting its own server and connects to the specified port instead.

Running the App

Running with Docker Compose

docker compose up --watch

Start the asset builder and the web server. The site will be served on port 5001. The --watch flag enables automatic rebuilds when files change.

Running Locally

carton exec plackup -p 5001 -r

If you'd like to use Gazelle rather than the default Plack server:

carton exec plackup -p 5001 -s Gazelle -r

Linting and Tidying with Precious

This project uses precious to run linters and tidiers (perltidy, perlcritic, perlimports, eslint, prettier, omegasort).

Running via Docker

The test Docker image includes all linting tools. No local installation needed:

docker compose --profile test run --rm test precious lint --git
docker compose --profile test run --rm test precious tidy --git

Running Locally

If you prefer to run precious locally, install it with:

./bin/install-precious /usr/local/bin

Pre-commit Hook

You will want to set up the supplied pre-commit Git hook like so:

./git/setup.sh

which causes precious to be run before each commit.

Local Configuration Changes

The back end defaults to api.metacpan.org/v1. Running a local API server is optional and not required to hack on the front end. The address to the API being used can be changed in the metacpan_web.yaml file. Ideally you would create a new file called metacpan_web_local.yaml that contains

api: http://127.0.0.1:5000

which will be loaded on top of the existing config file.

Compatibility Notes

On Win32 (and possibly also on other platforms) when using Perl < 5.12, the server started with plackup will generate warnings relating to date parsing. These are caused by Plack due to a bug in the gmtime implementation and can be removed by upgrading to Perl 5.12.