Monorepo & Nx Task Runner

Open Web Desktop is managed as a monorepo using pnpm workspaces for package linking and dependency resolution, and Nx for task orchestration, caching, and release automation.

1. Monorepo Structure & pnpm Workspaces

All internal packages, modules, themes, and applications live in a single repository. The linking between these packages is defined in pnpm-workspace.yaml:

packages:
  - 'packages/*'
  - 'apps/*'
  - 'themes/*'
  - 'desktop'
  - 'docs'

Using pnpm workspaces allows packages to refer to each other locally (e.g., using workspace:* in package.json). During development, changes in @owdproject/core are instantly available inside local apps and themes without needing to publish to npm.

2. Nx Task Orchestration

While pnpm links the folders, Nx coordinates running scripts and build pipelines across the monorepo.

Dependency Task Pipelines

Instead of manually building dependencies, Nx understands how packages relate to each other. We define pipelines inside the root nx.json under targetDefaults.

For example, when running a test or build on a theme, Nx knows that @owdproject/core must be built first. It automatically runs the core module compilation in the correct order:

"targetDefaults": {
  "test": {
    "dependsOn": ["^build"]
  }
}

(The ^ symbol specifies that the task depends on the build target of all upstream dependencies).

Local Task Caching

Nx caches the output of successful builds, lints, and tests. If you run a build or test command on a package and the code has not changed, Nx restores the output from the cache in 0 milliseconds.

Visualizing the Workspace Graph

You can inspect how all packages, modules, themes, and apps are connected by running:

pnpm nx graph

This launches an interactive browser graph showing OWD's dependency tree.

3. Automated Releases (nx release)

OWD uses nx release to orchestrate independent version bumps, autogenerate changelogs, create Git tags, and automate npm publishing.

Versioning Model

OWD uses an independent versioning model (configured in nx.json under the release block). This means different packages (e.g., @owdproject/core, @owdproject/cli, or themes) can be versioned and published independently.

Running a Release (Maintainers)

When you are ready to prepare a release:

1. Commit your changes using Conventional Commits (e.g. feat: add new window snapping, fix: resolve drag bounds offset).
2. Run a Dry Run: Inspect what version bumps and changelog updates Nx will generate without writing changes:

   pnpm nx release --dry-run
   

3. Execute the Release: Bump versions, update changelogs, commit, and create Git tags locally:

   pnpm nx release
   

4. Push the Tags: Push your commits and tags to GitHub:

   git push origin main --tags
   

GitHub Actions Publishing

Once you push a tag starting with v* (e.g. v3.4.2), our GitHub Action workflow .github/workflows/publish.yml automatically triggers. It will:

• Run linting and test suites.
• Build @owdproject/core and other packages.
• Run pnpm publish -r --no-git-checks --access public to publish the updated packages to npm using a secure NPM_TOKEN repository secret.