The LWC monorepo: the engine, the compiler and the release machinery behind Lightning Web Components

An engine and a compiler in one workspace

This repository contains the source code for the Lightning Web Components Engine and Compiler. Additionally, it contains examples, documentation, meeting notes and discussion notes for developers contributing or using Lightning Web Components.

That list is a good description of the project's shape. An engine and a compiler are two different pieces with two different audiences: the engine is what runs in the browser at runtime, and the compiler is what turns your component source into something the browser can load. Shipping them from one repository means the compiler and the engine are versioned together, which matters when a compiler emits output that only a matching engine understands.

The repository is a monorepo. The root `package.json` is named `lwc-monorepo`, it is marked private, it declares `type: module`, and the version in it is 9.5.1, which matches the newest published release. The tree shows the shape of the work: `packages/` holds the publishable pieces, `playground/` is a place to try things, `scripts/` holds the tasks that are not part of a package, and `docs/` is part of what the README promises to ship.

The intended user is a developer working on Lightning Web Components themselves, either as a Salesforce engineer building components for a platform, or as a contributor to the framework. The homepage is lwc.dev, the default branch is `master`, and the last push was on 2026-10-14 with the repository not archived. The recent releases are v9.5.1 from 2026-10-14, v9.3.10 from 2026-09-21 and v9.3.9 from 2026-09-09, which is a release cadence of roughly every two to three weeks for a framework that is versioned in the nines.

What ships in the tree beyond the code

The interesting part of a platform repository is often what sits around the code, and this one has a lot.

There is `ARCHITECTURE.md` and `AGENTS.md`, which is the convention this ecosystem uses for guidance that tools and contributors are expected to read. There is `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `SECURITY.md`, so the repository treats a vulnerability report and a pull request as first class entry points.

The tooling is where the maturity shows. `nx.json` is the Nx configuration, and Nx is what orchestrates the build across dozens of packages in `packages/`. `vitest.config.mjs` and `vitest.shared.mjs` configure the unit test runner. `eslint.config.mjs` is the flat ESLint configuration, and `.prettierrc` with `.prettierignore` is the formatting setup. `commitlint.config.js` and the `.husky/` directory handle the commit hooks, and `nx.json` and `scripts/` carry the release tasks. `.strata.yml` is the configuration for Strata, the release tool Salesforce uses to cut and publish versions across a set of packages, and `yarn.lock` is the dependency lockfile for the Yarn workspace, with `.npmrc` holding the registry configuration.

Two directories deserve a note. `scripts/bundlesize/` holds the bundlesize check, which is the mechanism that fails a build when a package grows past a size budget, and given that LWC describes itself as a foundation for enterprise web components, a hard limit on shipped bytes is a design constraint rather than a nice extra. And `playground/` is a place to run components in isolation, which is the tool you want when a component behaves differently in a bundle than it does in isolation.

The `packages/` directory is where the publishable modules live, and the build script's exclude list gives a glimpse of their names: `@lwc/perf-benchmarks`, `@lwc/perf-benchmarks-components` and `@lwc/integration-wdio` are excluded from a normal build because they are test infrastructure rather than shipping packages.

Four test suites, and the badges that track them

The README carries four CI badges, and they map onto four distinct kinds of test, which is more informative than a single green tick.

The first is the unit tests workflow, `unit.yml`. The second is the web-test-runner workflow, `web-test-runner.yml`, which runs the browser-based component tests in a real browser rather than in a JavaScript environment. The third is the integration workflow, `integration.yml`, which exercises the packages together. The fourth is the benchmark workflow, `benchmark.yml`, labelled performance tests.

The distinction matters for a web components framework, because the failure modes it has are not the ones a normal library has. A component can pass every unit test and still fail in a browser because of a custom element registration problem, a shadow DOM lifecycle issue, or a server side rendering pass that behaves differently from the client. The web-test-runner suite exists because the browser is the runtime that matters.

The scripts show how each suite is invoked. Unit and component tests run through Vitest, with `test` mapping to `vitest` and `test:ci` to `vitest run --coverage`. The web-test-runner integration suite is `nx test @lwc/integration-wtr`, and there is a separate `test:hydration` target for hydration testing. The browser-driven integration suite runs through WebdriverIO with `nx sauce @lwc/integration-wdio`, which is a Sauce Labs configuration, so the integration tests are expected to run across real browser environments rather than only locally. The performance suite is `nx test @lwc/perf-benchmarks`, with a `test:performance:best` variant and a separate `build:performance` target that builds the benchmark components before the benchmarks run.

There is also a `test:debug` script that runs `vitest --inspect-brk --no-file-parallelism`, which breaks into the debugger and serialises the files, which is what you want when a test fails only in a parallel run.

Nx and Yarn: how the build is orchestrated

The build commands in the root `package.json` are the clearest description of how the repository is put together.

The build is `nx run-many --target=build` with three packages excluded, and the development mode is `nx run-many --target=dev --all --parallel=999` with the same exclusions. Nx is doing the dependency graph, the caching and the fan out, and the `--parallel=999` figure in the dev script tells you that a developer running the watch mode gets every package building at once rather than a curated subset.

The exclusion list is worth reading closely, because the three excluded packages are the expensive ones: the performance benchmarks, the benchmark components, and the WebdriverIO integration suite. A normal build is fast because it is not building the test scaffolding, and the performance and browser suites are invoked through their own targets when they are needed.

The remaining scripts cover the rest of the workflow. `prepare` runs `husky && yarn build`, so a fresh clone installs the git hooks and builds the workspace. `lint` is `eslint . --cache`, which explains the `eslint.config.js` flat configuration, and `format` is `prettier --write .`. `bundlesize` is `node scripts/bundlesize/bundlesize.mjs`, run as its own script rather than as part of the build, which suggests it is a check in a separate workflow or a manual step.

The test surface is broad, and it is worth noticing how many entry points exist for the same underlying code. `test` and `test:production`, which sets `VITE_NODE_ENV=production`, run the same suite against a production build, and `test:bespoke` runs the per-package tests through Nx. `test:types` runs the type-level integration tests, which for a framework whose main output is compiled templates and generated code is a meaningful category rather than a formality.

The `packages/` layout with a `packages/` scope prefix, the `@lwc/` naming, and the private root package with a `version` field that tracks the release train are all consistent with a workspace where every package is versioned and published together, which is what a framework like this needs.

Release engineering, and the two licence files

The versioning is handled by tooling rather than by hand, and the pieces are visible in the tree. `commitlint.config.js` enforces the commit message format, and `release-please` is referenced by the presence of `release:version` and the release configuration, with the GitHub Actions workflows alongside. The `.strata.yml` file points at Strata, the tool Salesforce uses to coordinate a release across many packages, which is what a monorepo with dozens of published packages needs and a single-package repository does not.

The result is a release train. The recent tags, v9.5.1, v9.3.10 and v9.3.9, move the whole suite forward together, and the root `package.json` version of 9.5.1 tracks the newest one.

The licence needs a sentence of its own, because the repository ships two files. There is `LICENSE.md` and `LICENSE-CORE.md`, the README states that the MIT license governs your use of Lightning Web Components, and the project metadata records the licence as other, a custom licence that GitHub cannot classify. The two files are not the same document, and the core one is named in a way that suggests a separate grant for the framework's core.

For anyone shipping a component library built on LWC, the practical point is that you need to read both files and know which parts of the framework you are redistributing, because the runtime and the compiler may not be under the same terms. That is a description of the files rather than legal advice, and it is worth a few minutes with your own compliance process before you publish a bundle that embeds the engine.

Where LWC is the wrong choice

There are three situations where this repository is not what you want, and they are worth separating from the case where it clearly is.

The first is a generic web component project outside the Salesforce platform. The engine and the compiler here are built for Lightning Web Components and their template model, and while LWC's web component implementation is open and readable, adopting it for a project that has no relationship to Salesforce means owning a compiler and a runtime whose conventions come from somewhere else.

The second is when you need a stable, frozen API and expect one. This is a moving target on a two to three week release cadence, with the major version at nine and the minor version carrying the framework's own breaking-change budget. A platform team that wants quarterly upgrades with a compatibility review will find the pace demanding, and a team that wants to pin a version will find the tags there but will not find a stated support policy for them.

The third is when you want the framework without the platform, or the platform without the framework. The Salesforce platform ships its own versions of LWC, and the version of the engine that runs in a given Salesforce org is not necessarily the version in the newest tag, which is a mismatch a self-hosted component developer has to plan for.

The alternative approach, for comparison, is the platform itself. If your application is a Salesforce app, the LWC compiler and engine that ship with the platform are already there, versioned together with everything else, and using the repository build instead means you now own the compatibility between your components and the org they run in.

And the thing the repository is genuinely for is contribution. The contributing documentation, the roadmap, the meeting notes, the discussion notes and the good first issue labels all point at a project that wants to be developed in the open. A team that wants to change how the engine schedules updates, or add a data adapter, is the intended user here, and for anyone else the platform's own implementation is the better dependency.

Editorial conclusion

Adopt the LWC repository if you are building Lightning Web Components, because it is the only place the engine, the compiler, the templates and the test harnesses exist together, and the four test suites plus the bundlesize check are what keep a web component framework honest. Do not adopt it as a general web component library for a project outside the Salesforce platform, since the compiler and the runtime assumptions are tied to the platform, and do not expect the MIT grant to cover the core. Verify three things first: which of the two licence files applies to the part you are using, since the repository ships both `LICENSE.md` and `LICENSE-CORE.md` while the README points at the MIT licence, the version of the compiler your platform expects against the tag you are building from, and that the test suite you rely on actually runs in your environment, because the integration suites need a browser and the performance suites need their own build targets.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. salesforce/lwc on GitHub