How to Deploy & Use prettier/prettier

# Prettier Deploy/Usage Guide

Comprehensive guide for building, developing, and deploying Prettier from source.

## 1. Prerequisites

- **Node.js**: Version 18.x or higher (Latest LTS recommended)
- **Package Manager**: npm 9+, Yarn 1.22+, or pnpm 8+
- **Git**: For cloning and version control
- **Operating System**: Linux, macOS, or Windows (WSL recommended for Windows development)

Verify prerequisites:
```bash
node --version  # v18.0.0 or higher
npm --version   # 9.0.0 or higher
git --version   # 2.30.0 or higher

2. Installation

Clone Repository

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

Install Dependencies

npm install

This installs all build tools, testing frameworks, and development dependencies. The installation may take 2-3 minutes depending on network speed.

3. Configuration

Environment Variables

No additional environment variables are required for basic development. Optional variables for advanced use:

# Development mode (skips minification for faster builds)
export NODE_ENV=development

# Custom dist directory (defaults to ./dist)
export DIST_DIR=/path/to/custom/dist

Prettier Configuration

The project uses its own formatting rules. Configuration is defined in:

.prettierrc - Core formatting rules (trailing commas, single quotes, etc.)
.editorconfig - Editor indentation and whitespace settings

Do not modify these files unless contributing a formatting change to the entire codebase.

4. Build & Run

Development Workflow

Build the package (required before testing distribution):

npm run build

This creates:

dist/prettier/ - Built package files
ESM (.mjs), CommonJS (.cjs), and UMD (.js) bundles
Type definitions (.d.ts)

Watch mode (rebuilds on file changes):

npm run build -- --watch

Run tests:

# Full test suite (lint + unit tests + integration)
npm test

# Unit tests only
npm run test:unit

# Tests against built distribution
npm run test:dist

# Specific language tests
npm run test:unit -- tests/integration/language-js/

Lint and format:

# Check code style
npm run lint

# Auto-fix issues (uses Prettier itself)
npm run fix

Local Usage Testing

Link the built package locally to test in other projects:

cd dist/prettier
npm link

# In your test project
npm link prettier

5. Deployment

Publishing to npm (Maintainers)

Build production assets:
```
NODE_ENV=production npm run build
```
Verify build integrity:
```
npm run test:dist
npm run test:package
```
Publish:
```
cd dist/prettier
npm publish
```

CI/CD Integration

For integration into continuous deployment pipelines:

# Example GitHub Actions workflow
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - run: npm ci
  - run: npm run build
  - run: npm test
  - run: npm publish ./dist/prettier
    env:
      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Docker Deployment

Create a containerized formatter service:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/prettier ./dist
ENTRYPOINT ["node", "./dist/bin/prettier.js"]

Build and run:

docker build -t prettier-local .
docker run --rm -v $(pwd):/app prettier-local --write "**/*.js"

6. Troubleshooting

Build Failures

Error: Cannot find module 'esm-utils' or ESM-related errors

Ensure Node.js version is 18+
Clear npm cache: npm cache clean --force
Delete node_modules and reinstall: rm -rf node_modules && npm install

Error: DIST_DIR not found

Create the directory manually or run from project root: mkdir -p dist/prettier

Module resolution errors in built files

The build process replaces certain modules (e.g., editorconfig-without-wasm, n-readlines). If modifications fail:
- Check scripts/build/packages/prettier.js for the replaceModule array
- Ensure regex patterns match current dependency versions

Test Failures

Snapshot mismatches

Update snapshots if changes are intentional: npm run test:unit -- --updateSnapshot
Verify only intended files changed: git diff tests/

AST parsing errors

Ensure no syntax errors in modified source files
Run specific failing test with verbose output: npm run test:unit -- --verbose path/to/test.js

Performance Issues

Slow builds

Use development mode: NODE_ENV=development npm run build
Exclude heavy test suites temporarily: npm run test:unit -- --testPathIgnorePatterns=tests/integration

Out of memory during build

Increase Node heap size: NODE_OPTIONS=--max-old-space-size=4096 npm run build

npm Link Issues

Permission errors on global link

Use local linking instead: npm install /path/to/prettier/dist/prettier
Or use npx to test locally: npx /path/to/dist/prettier --help