Build System and Tooling

OpenLayers uses a comprehensive build system based on npm scripts and modern JavaScript tooling to transform TypeScript source code into distributable packages. This system handles transpilation, bundling, type generation, testing, and development workflow automation.

Build Pipeline Architecture

The build pipeline transforms source files through multiple stages using npm scripts defined in package.json. The pipeline handles TypeScript compilation, module bundling, and package preparation.

Build Pipeline Flow

100%

Core Build Scripts

The build system uses npm scripts that orchestrate file operations, transpilation, and bundling:

Script	Command	Purpose
transpile	shx rm -rf build/ol && shx mkdir -p build/ol && shx cp -rf src/ol build && node tasks/serialize-workers.cjs && node tasks/set-version.js	Prepares source files, processes workers, sets version
build-index	shx rm -f build/index.js && npm run transpile && node tasks/generate-index.js	Creates main module entry point
build-full	shx rm -rf build/full && npm run build-index && npx rollup --config config/rollup-full-build.js	Bundles library using Rollup
copy-css	shx cp src/ol/ol.css build/ol/ol.css	Copies CSS stylesheet
generate-types	tsc --project config/tsconfig-build.json --declaration --declarationMap --emitDeclarationOnly --outdir build/ol	Generates TypeScript declarations
build-package	npm run build-full && npm run copy-css && npm run generate-types && node tasks/prepare-package.js	Assembles final distribution package

Build Process Steps

1. Transpilation (transpile)

This initial step prepares the source files for further processing:

• Cleans the build/ol directory
• Creates necessary directories
• Copies source files from src/ol to build
• Processes web worker files via serialize-workers.cjs
• Sets version information via set-version.js

2. Index Generation (build-index)

This step creates the main entry point:

• Removes any existing build/index.js
• Ensures transpilation is complete
• Generates an index file from the transpiled source using generate-index.js

3. Full Build (build-full)

This step creates a bundled version of the library:

• Cleans the build/full directory
• Ensures the index is generated
• Uses Rollup to create a bundled version with all dependencies

4. Type Generation (generate-types)

This step creates TypeScript declaration files:

• Uses TypeScript compiler with a specific configuration
• Generates .d.ts and .d.ts.map files
• Outputs to build/ol directory

5. Package Creation (build-package)

This final step creates the complete distribution package:

• Ensures the full build is complete
• Copies CSS files to the build directory
• Ensures type declarations are generated
• Prepares the final package for distribution via prepare-package.js

Dependency Management

OpenLayers maintains a minimal runtime footprint with only five production dependencies while using an extensive development toolchain for building, testing, and development.

Runtime Dependencies

100%

Development Toolchain Dependencies

Category	Key Dependencies	Purpose
Build Tools	rollup@^4.1.4, typescript@5.8.3, webpack@^5.27.2	Module bundling and compilation
Testing	karma@^6.3.8, mocha@11.7.1, puppeteer@24.16.1	Browser and Node.js testing
Code Quality	eslint@^9.16.0, eslint-config-openlayers@^20.0.0	Linting and style enforcement
Documentation	jsdoc@4.0.4, metalsmith@^2.5.0, marked@16.1.2	API docs and examples
Development	webpack-dev-server@^5.0.2, express@^5.1.0	Development server

Testing Infrastructure

OpenLayers implements a multi-layered testing strategy covering code quality, type safety, unit tests, integration tests, and visual regression testing.

Testing Pipeline

100%

Karma Browser Testing Configuration

The browser test environment uses Karma with sophisticated webpack integration:

100%

Test Categories

Test Type	Runner	Configuration	Purpose
Linting	ESLint	eslint-config-openlayers	Code style and quality
Type Checking	TypeScript	tsconfig.json, config/tsconfig-strict.json	Type safety
Unit Tests	Karma + Mocha	test/browser/karma.config.cjs	Browser compatibility
Node Tests	Mocha	test/node/	Server-side functionality
Visual Tests	Custom	test/rendering/	Rendering accuracy

Development Workflow

OpenLayers provides dedicated npm scripts for different development scenarios, from core library development to examples and documentation.

Development Server Setup

100%

Core Development Workflows

Workflow	Commands	Purpose
Library Development	npm run transpile → npm test → npm run build-package	Core library changes
Example Development	npm start → edit → refresh browser	Interactive examples
API Documentation	npm run apidoc	Generate documentation
Full Release Build	npm run build-package	Distribution preparation

Example Development Process

The examples system provides immediate feedback for development:

1. Start Development Server: npm start launches webpack-dev-server with hot reloading
2. Live Development: Changes to example code automatically refresh the browser
3. Production Build: npm run build-examples creates optimized examples in build/examples/

Build Outputs

The build process creates these outputs:

Output	Location	Description
Transpiled Source	build/ol/	Processed source files
Index File	build/index.js	Main entry point
Full Build	build/full/	Bundled library
TypeScript Declarations	build/ol/*.d.ts	Type definitions
CSS	build/ol/ol.css	Stylesheet
Package	build/	Complete distribution package

API Documentation Generation

OpenLayers also includes scripts for generating API documentation:

Script	Purpose
apidoc	Generates API documentation using JSDoc
apidoc-debug	Generates API documentation with debugging enabled

These scripts use JSDoc with a custom configuration to generate documentation from the source code comments.

Examples Building

The example system has dedicated build scripts:

Script	Purpose
serve-examples	Starts a webpack dev server for examples
build-examples	Builds examples for production

The examples use webpack for bundling and development serving.