Development & Contributing
Relevant source files
The following files were used as context for generating this wiki page:
The nx-extend repository is a monorepo containing a collection of Nx plugins for deployment, infrastructure, testing, and development tools. It enables developers to extend Nx workspace capabilities through standardized executors and generators. Contributions help maintain compatibility with the latest Nx versions and expand the ecosystem of production-ready plugins.
Sources: README.md:3-8, README.md:162-167
Development Workflow
Development within the workspace follows standard Nx patterns for library and application management. Each plugin is located within the packages/ directory and contains its own project configuration, source code, and tests.
Plugin Architecture
Plugins consist of two primary components:
- Generators: Automate the creation and configuration of projects (e.g., Docusaurus apps or Strapi instances).
- Executors: Define specific tasks such as building, serving, or deploying applications.
The diagram shows the relationship between plugin logic and the configuration files that Nx uses to discover them.
Sources: packages/github-pages/project.json:11-54, packages/docusaurus/package.json:34-35
Standard Project Targets
Every package in the workspace defines a consistent set of targets in its project.json.
| Target | Executor | Description |
|---|---|---|
build | @nx/js:tsc | Compiles TypeScript source to the dist/ folder. |
lint | @nx/eslint:lint | Validates code style and quality. |
test | @nx/jest:jest | Runs unit and integration tests. |
version | @jscutlery/semver:version | Manages semantic versioning and changelogs. |
publish | nx:run-commands | Publishes the package to the npm registry. |
Sources: packages/github-pages/project.json:7-61
Generator Implementation
Generators implement the Tree and schema interfaces provided by @nx/devkit. They typically follow a specific lifecycle to ensure consistent project creation.
Generator Lifecycle
- Normalize Options: Converts raw user input into a standardized format, including project roots and directory structures.
- Add Configuration: Injects project settings into the workspace using
addProjectConfiguration. - Generate Files: Copies and processes templates from a
files/directory. - Update Workspace Configs: Modifies global files like
.gitignoreor.prettierignore. - Install Dependencies: Adds required npm packages to the root
package.json.
The sequence diagram illustrates the internal steps executed when a user runs a project generator.
Sources: packages/docusaurus/src/generators/application/generator.ts:24-150
Implementation Example
In packages/strapi/src/generators/init/init.impl.ts, the generator interacts with external CLI tools (e.g., @strapi/generate-new) while maintaining Nx integration by disabling the external tool's dependency installation and handling it via Nx tasks.
Sources: packages/strapi/src/generators/init/init.impl.ts:16-43
Release and Versioning
The project uses @jscutlery/semver to manage automated versioning. Releases are performed across the monorepo, often involving peer dependency bumps for @nx/devkit to maintain compatibility with new Nx versions.
Peer Dependency Management
Plugins maintain strict peer dependencies on @nx/devkit. When Nx is upgraded (e.g., to v21 or v22), all packages undergo a breaking change release to update these requirements.
Sources: packages/core/CHANGELOG.md:13-17, packages/docusaurus/package.json:26
Publication Process
Publishing is triggered via the publish target, which executes npm publish on the built artifacts in the dist/ directory.
nx publish <package-name>
Sources: packages/github-pages/project.json:57-61
Contributing Guidelines
The project welcomes community contributions via the GitHub repository.
- Issues: Open an issue for bug reports or feature requests.
- Discussions: Browse existing issues for technical discussions.
- Pull Requests: Submit PRs to address issues or add features.
- Formatting: Ensure code follows the workspace formatting rules; generators should not skip formatting unless the
skipFormatoption is explicitly true.
Sources: README.md:162-171, packages/docusaurus/src/generators/application/generator.ts:145-147
CI/CD Utilities
nx-extend provides built-in GitHub Actions to optimize CI/CD for Nx workspaces. Contributors and users should use these to streamline task execution.
| Action | Purpose |
|---|---|
set-shas | Configures SHAs for nx affected commands to identify changed projects. |
plan | Analyzes Nx tasks and creates execution plans. |
run-many | Executes multiple Nx targets efficiently in parallel. |
Sources: README.md:148-159
Development in this repository requires a clear understanding of the Nx Devkit and the relationship between core logic and the distributed plugins. Consistency in target definitions and generator structure ensures the stability of the nx-extend ecosystem.