Contributing to the expressjs.com website

April 22, 2026 · View on GitHub

This is the contribution documentation for the expressjs.com website.

You can see the current captains and committers of this project, and learn how to join through the governance document. Also review the Express Collaborator Guide for general contribution guidelines across Express.js projects.

Common Contributions

Website Issues: Improvements to the site's functionality, design, or accessibility.
Content Issues: Fix anything related to site content or typos.
Translation Issues: Fix translation errors or contribute new content. See the i18n documentation.

Working on Issues

We welcome contributions to existing bugs or enhancements. You can find these under our repo's Issues tab. Look for issues labeled good first issue or help wanted to get started.

If you have found a bug, a typo, or have an idea for an enhancement:

Submit a new issue for larger proposals or to get feedback first.
Open a pull request directly if the work is ready to go.

For significant changes, we encourage opening an issue first to discuss and align before starting work.

Getting Started

Prerequisites

This project uses:

Astro for site generation
TypeScript for type safety
ESLint for linting
Prettier for formatting

Tooling required:

Node.js: v24.x or higher
npm: v11.0.0 or higher (comes with Node 24)

We recommend using nvm to manage Node.js versions. This project includes an .nvmrc file for automatic version switching.

Setup

Clone the repository:

git clone https://github.com/expressjs/expressjs.com.git
cd expressjs.com

Install the correct Node.js version (if using nvm):
```
nvm install
nvm use
```
Install dependencies:
```
npm install
```
Start the development server:
```
npm run dev
```
The site will be available at http://localhost:4321

Available Scripts

Command	Description
`npm run dev`	Start development server with hot reload
`npm run build`	Build production site to `./dist`
`npm run preview`	Preview production build locally
`npm run lint`	Run ESLint to check for issues
`npm run check`	Run type checking and format verification
`npm run test:e2e`	Run Playwright E2E tests

Submitting a Pull Request

Create a new branch from main.
Make your changes.
Run npm run check to verify code style and types.
Run npm run test:e2e to ensure your changes don't break existing functionality.
Commit with a clear message.
Push to your fork.
Open a PR against main.

Ensure all checks pass and your branch is up to date with main before opening a PR.

Testing

We use Playwright for End-to-End (E2E) testing. All PRs are automatically tested against a Netlify Preview deployment before they can be merged.

Prerequisites

Before running E2E tests for the first time, you need to install the browser binaries:

npx playwright install --with-deps

Running Tests Locally

You can run the full test suite against your local development server:

In one terminal, start the site: npm run dev
In another terminal, run the tests: npm run test:e2e

Writing Stable Tests

When adding new tests or modifying components, please follow these stability guidelines:

Avoid CSS Classes: Do not use CSS classes (e.g., .hero__content) for locators, as they are fragile and change during refactoring.
Use data-testid: Add data-testid attributes to components for stable targeting (e.g., <div data-testid="my-component">).
User-Visible Locators: Prefer semantic locators like getByRole, getByText, or getByAltText over IDs when possible.

Example:

// Good: Stable and accessible
const logo = page.getByAltText('Express.js logo');
const section = page.getByTestId('features-section');

// Bad: Fragile
const logo = page.locator('.hero__logo');

Further Documentation

For more detailed documentation about the project, see the docs/ folder:

Project Structure — Architecture, folder layout, and framework policy
Content — Collections, frontmatter, versioning, and global pages
Configuration — Navigation menus, announcement bar, and version-specific items
Internationalization — Translations, Crowdin integration, and adding languages
Design System — Components, tokens, colors, typography, and breakpoints