-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add more complete explanations
- Loading branch information
Showing
3 changed files
with
174 additions
and
49 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,53 +1,136 @@ | ||
| # @push-based/build-env | ||
|
|
||
| ## To Research | ||
|
|
||
| - Store Verdaccio state under .nx? | ||
| - Project usage across existing Nx projects (popular open-source libraries?) | ||
| - Research if we can use Nx release Node.js API instead of custom target? | ||
| - How to ensure the setup will work in Nx Agents? | ||
|
|
||
| **What can be cached** | ||
|
|
||
| - `setup-env` | ||
| - npm workspace folder (.npmrc, package-lock.json, node_modules) | ||
| - `npm-publish` | ||
| - inputs | ||
| - build output, using dependent task output? careful though, [it is known to struggle with Nx cloud agents](https://github.com/nrwl/nx/issues/22745) | ||
| - outputs | ||
| - list of packages in registry under `.../storage/.verdaccio-db.json` e.g.: `{"list":["<package-name>"],"secret":"esKM34zA53wetObgi5f0Uu1e7iObmm+f"}`` | ||
| - tarball of package under `.../storage/@push-based/<package-name>-<version>.tgz` | ||
| e.g.: `{workspaceRoot}/${environmentsDir}/{args.environmentProject}/storage/@push-based/${packageName}`, | ||
| - `package.json` of package under `.../storage/@push-based/<package-name>/package.json` | ||
| - `npm-install` | ||
| - outputs | ||
| - list of installed packages under `.../package.json` | ||
| - list of installed packages under `.../package-lock.json` | ||
| - source of package under `.../node_modules/@push-based/<package-name>/*` | ||
| mehh, we know the node_modules reputation | ||
| - inputs: | ||
| - output of npm-publish(?), package.json | ||
| - concerns: chicken-egg problem. | ||
| - when only caching `package-lock.json`, we still need to run `<packageManager> install`, separate install in 2 steps? | ||
| - when caching node_modules, obviously cache takes lot of room! | ||
| - to install dependencies and generate lock file, we need the Verdaccio server running | ||
|
|
||
| **Caching scenarios** | ||
|
|
||
| 1. what can be cached? | ||
| 2. is more small caches better | ||
| 3. how to visualize scenarios | ||
|
|
||
| - what is a worse/best case for e2e tests | ||
|
|
||
| ### Generators | ||
|
|
||
| #### Configuration | ||
|
|
||
| Adds a `build-env` target to your `project.json`. | ||
| See [configuration docs](./src/generators/configuration/README.md) for details | ||
| ## Plugins | ||
|
|
||
| ### Build Environment Plugin | ||
|
|
||
| Add dynamic targets to execute environment tasks. | ||
|
|
||
| See [build-environment plugin docs](./src/plugin/README.md) for details | ||
|
|
||
| Examples: | ||
|
|
||
| - `nx g @push-based/build-env:configuration --project=<project-name>` | ||
| - `nx g @push-based/build-env:configuration --project=<project-name> --targetName=cp` | ||
| - `nx g @push-based/build-env-env-setup` - generates NPM workspace and installs packages | ||
| - `nx g @push-based/build-env-env-setup --keepServerRunning` - keeps Verdaccio running for debug reasons | ||
|
|
||
| ## Executor | ||
|
|
||
| ### Setup Environment Executor | ||
|
|
||
| This executor helps to initiate an [environment folder](../../../../../README.md#-environment-folders-to-isolate-files-during-e2e-tests) and installs it`s dependent projects. | ||
|
|
||
| // project.json | ||
|
|
||
| ```jsonc | ||
| { | ||
| "name": "my-project", | ||
| "targets": { | ||
| "build-env--env-bootstrap": { | ||
| "executor": "@code-pushup/build-env:env-bootstrap", | ||
| "options": { | ||
| "keepServerRunning": false | ||
| "envRoot": "/tmp/test-npm-workspace" | ||
| "verbose": true, | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Read more under [setup executor docs](./projects/build-env/src/executors/setup/README.md). | ||
|
|
||
| ### Bootstrap Environment Executor | ||
|
|
||
| This executor helps to initiate [environment](../../../../../README.md#-environment-folders-to-isolate-files-during-e2e-tests) into a given folder. | ||
|
|
||
| // project.json | ||
|
|
||
| ```jsonc | ||
| { | ||
| "name": "my-project", | ||
| "targets": { | ||
| "build-env--env-bootstrap": { | ||
| "executor": "@code-pushup/build-env:env-bootstrap", | ||
| "options": { | ||
| "keepServerRunning": false | ||
| "envRoot": "/tmp/test-npm-workspace" | ||
| "verbose": true, | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Read more under [bootstrap executor docs](./projects/build-env/src/executors/bootstrap/README.md). | ||
|
|
||
| ### Kill Process Executor | ||
|
|
||
| This executor helps to kill processes by `ProcessID` or a JSON file containing a property `pid` as number. | ||
|
|
||
| // project.json | ||
|
|
||
| ```jsonc | ||
| { | ||
| "name": "my-project", | ||
| "targets": { | ||
| "build-env--kill-process": { | ||
| "executor": "@push-based/build-env:kill-process" | ||
| "options": { | ||
| "pid": "42312" | ||
| "filePath": "/tmp/test-npm-workspace/process-id.json" | ||
| "verbose": true, | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Read more under [kill-process executor docs](./projects/build-env/src/executors/kill-process/README.md). | ||
|
|
||
| ### NPM Install Executor | ||
|
|
||
| This executor helps to install a [`pubishable`](../../../../../README.md#fine-grained-selection-of-publishable-projects) projects into a given [environment folder](../../../../../README.md#-environment-folders-to-isolate-files-during-e2e-tests). | ||
|
|
||
| // project.json | ||
|
|
||
| ```jsonc | ||
| { | ||
| "name": "my-project", | ||
| "targets": { | ||
| "build-env--npm-install": { | ||
| "executor": "@code-pushup/build-env:release-install", | ||
| "options": { | ||
| "pkgVersion": "1.2.3" | ||
| "envRoot": "/tmp/test-npm-workspace" | ||
| "verbose": true, | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Read more under [release install executor docs](./projects/build-env/src/executors/npm-install/README.md). | ||
|
|
||
| ### NPM Publish Executor | ||
|
|
||
| This executor helps to publish a [`pubishable`](../../../../../README.md#fine-grained-selection-of-publishable-projects) projects into a given [environment folder](../../../../../README.md#-environment-folders-to-isolate-files-during-e2e-tests). | ||
|
|
||
| // project.json | ||
|
|
||
| ```jsonc | ||
| { | ||
| "name": "my-project", | ||
| "targets": { | ||
| "build-env--npm-publish": { | ||
| "executor": "@code-pushup/build-env:release-publish", | ||
| "options": { | ||
| "pkgVersion": "1.2.3" | ||
| "envRoot": "/tmp/test-npm-workspace" | ||
| "verbose": true, | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Read more under [release publish executor docs](./projects/build-env/src/executors/npm-publish/README.md). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # BuildEnv Plugin | ||
|
|
||
| This plugin helps to add dynamic targets to execute environment tasks. | ||
| This distinguishes between projects that maintain publishable packages and e2e test projects that depend on an environment where the publishable projects get installed. | ||
|
|
||
| #### @push-based/build-env | ||
|
|
||
| ## Usage | ||
|
|
||
| // `nx.json`: | ||
|
|
||
| ```jsonc | ||
| { | ||
| "plugins": [ | ||
| { | ||
| "plugin": "@push-based/build-env", | ||
| "options": { | ||
| "environments": { | ||
| "environmentsDir": "tmp/environments" // Optional | ||
| "targetNames": ["e2e"] // Optional | ||
| } | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Now run your e2e test with `nx run utils-e2e:e2e` | ||
|
|
||
| ## Options | ||
|
|
||
| | Name | type | description | | ||
| | -------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------- | | ||
| | **environments.environmentsDir** | `string` (DEFAULT 'tmp/environments') | The folder name of the generated environments | | ||
| | **environments.targetNames** | `string[]` (REQUIRED) | The target names of projects depending on environments | | ||
| | **environments.filterByTag** | `string[]` (REQUIRED) | The tag names a projects needs to have to be considered for a environments (match is one of) | | ||
| | **publishable.filterByTag** | `string[]` (REQUIRED) | The tag names a projects needs to have to be considered for publishing (match is one of) | | ||
|
|
||
| **Example usage:** | ||
|
|
||
| - `nx run utils-e2e:e2e` - setup environment and then run E2E tests for `utils-e2e` | ||
| - `nx run utils-static-e2e:e2e --environmentRoot static-environments/user-lists` - setup NPM in existing environment and then run E2E tests for `utils-static-e2e` |