diff --git a/projects/build-env/README.md b/projects/build-env/README.md index 38c68289..7dbcd02b 100644 --- a/projects/build-env/README.md +++ b/projects/build-env/README.md @@ -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":[""],"secret":"esKM34zA53wetObgi5f0Uu1e7iObmm+f"}`` - - tarball of package under `.../storage/@push-based/-.tgz` - e.g.: `{workspaceRoot}/${environmentsDir}/{args.environmentProject}/storage/@push-based/${packageName}`, - - `package.json` of package under `.../storage/@push-based//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//*` - 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 ` 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=` -- `nx g @push-based/build-env:configuration --project= --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). diff --git a/projects/build-env/src/executors/bootstrap/bootstrap-env.ts b/projects/build-env/src/executors/bootstrap/bootstrap-env.ts index fe74d73c..f5d85cc7 100644 --- a/projects/build-env/src/executors/bootstrap/bootstrap-env.ts +++ b/projects/build-env/src/executors/bootstrap/bootstrap-env.ts @@ -15,11 +15,7 @@ import { VERDACCIO_ENV_TOKEN, } from './npm'; -export type BootstrapEnvironmentOptions = StartVerdaccioOptions & - Environment & { - projectName: string; - environmentRoot: string; - }; +export type BootstrapEnvironmentOptions = StartVerdaccioOptions & Environment; export type BootstrapEnvironmentResult = Environment & { registry: VercaddioServerResult; diff --git a/projects/build-env/src/executors/bootstrap/executor.ts b/projects/build-env/src/executors/bootstrap/executor.ts index 52cdbe06..ad4b3e66 100644 --- a/projects/build-env/src/executors/bootstrap/executor.ts +++ b/projects/build-env/src/executors/bootstrap/executor.ts @@ -39,7 +39,6 @@ export async function bootstrapExecutor( bootstrapResult = await bootstrapEnvironment({ projectName, environmentRoot, - keepServerRunning, }); } catch (error) { logger.error(error); diff --git a/projects/build-env/src/executors/bootstrap/schema.json b/projects/build-env/src/executors/bootstrap/schema.json index e695dbcd..7f58d5f6 100644 --- a/projects/build-env/src/executors/bootstrap/schema.json +++ b/projects/build-env/src/executors/bootstrap/schema.json @@ -6,12 +6,14 @@ "properties": { "environmentRoot": { "type": "string", - "description": "The root directory of the environment" + "description": "The root directory of the environment", + "aliases": ["envRoot", "e"] }, "keepServerRunning": { "type": "boolean", "description": "Keep the server running after the bootstrap commands have been executed", - "default": true + "default": true, + "aliases": ["k"] }, "printConfig": { "type": "boolean", diff --git a/projects/build-env/src/executors/bootstrap/verdaccio-registry.ts b/projects/build-env/src/executors/bootstrap/verdaccio-registry.ts index 7bc907d9..0926a323 100644 --- a/projects/build-env/src/executors/bootstrap/verdaccio-registry.ts +++ b/projects/build-env/src/executors/bootstrap/verdaccio-registry.ts @@ -58,7 +58,7 @@ export function parseRegistryData(stdout: string): VerdaccioProcessResult { } export type StarVerdaccioOnlyOptions = { - projectName?: string; + projectName: string; verbose?: boolean; }; diff --git a/projects/build-env/src/executors/kill-process/schema.json b/projects/build-env/src/executors/kill-process/schema.json index 437dd2e1..0cebb785 100644 --- a/projects/build-env/src/executors/kill-process/schema.json +++ b/projects/build-env/src/executors/kill-process/schema.json @@ -15,7 +15,8 @@ }, "environmentRoot": { "type": "string", - "description": "The root directory for the environment" + "description": "The root directory for the environment", + "aliases": ["envRoot", "e"] }, "filePath": { "type": "string", diff --git a/projects/build-env/src/executors/npm-install/schema.json b/projects/build-env/src/executors/npm-install/schema.json index a8b09d9e..5efa9410 100644 --- a/projects/build-env/src/executors/npm-install/schema.json +++ b/projects/build-env/src/executors/npm-install/schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/schema", - "$id": "KillProcessExecutorOptions", - "title": "A executor to kill processes by PID, command, or file", + "$id": "InstallExecutorOptions", + "title": "A executor to install a package", "type": "object", "properties": { "printConfig": { @@ -15,7 +15,8 @@ }, "environmentRoot": { "type": "string", - "description": "The root directory for the environment" + "description": "The root directory for the environment", + "aliases": ["envRoot", "e"] }, "filePath": { "type": "string", diff --git a/projects/build-env/src/executors/npm-install/schema.ts b/projects/build-env/src/executors/npm-install/schema.ts index 06b7e80a..555cb924 100644 --- a/projects/build-env/src/executors/npm-install/schema.ts +++ b/projects/build-env/src/executors/npm-install/schema.ts @@ -1,6 +1,5 @@ export type NpmInstallExecutorOptions = Partial<{ pkgVersion: string; - environmentProject: string; verbose: boolean; printConfig: boolean; environmentRoot: string; diff --git a/projects/build-env/src/executors/npm-publish/README.md b/projects/build-env/src/executors/npm-publish/README.md index 4f0de4d9..0c753ea3 100644 --- a/projects/build-env/src/executors/npm-publish/README.md +++ b/projects/build-env/src/executors/npm-publish/README.md @@ -1,4 +1,4 @@ -# NPM Install Executor +# 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). This folder has to contain all needed configuration and files for the `npm publish` command to work. diff --git a/projects/build-env/src/executors/npm-publish/schema.json b/projects/build-env/src/executors/npm-publish/schema.json index cb42944d..5fb0af2c 100644 --- a/projects/build-env/src/executors/npm-publish/schema.json +++ b/projects/build-env/src/executors/npm-publish/schema.json @@ -1,7 +1,7 @@ { "$schema": "http://json-schema.org/schema", - "$id": "KillProcessExecutorOptions", - "title": "A executor to kill processes by PID, command, or file", + "$id": "PublishExecutorOptions", + "title": "A executor to publish NPM packages", "type": "object", "properties": { "printConfig": { @@ -11,7 +11,8 @@ }, "environmentRoot": { "type": "string", - "description": "The root folder of the environment" + "description": "The root folder of the environment", + "aliases": ["envRoot", "e"] }, "verbose": { "type": "boolean", diff --git a/projects/build-env/src/executors/setup/schema.json b/projects/build-env/src/executors/setup/schema.json index bc641bd1..83f48fd4 100644 --- a/projects/build-env/src/executors/setup/schema.json +++ b/projects/build-env/src/executors/setup/schema.json @@ -6,12 +6,14 @@ "properties": { "environmentRoot": { "type": "string", - "description": "The root directory of the environment" + "description": "The root directory of the environment", + "aliases": ["envRoot", "e"] }, "keepServerRunning": { "type": "boolean", "description": "Keep the server running after the bootstrap commands have been executed", - "default": true + "default": true, + "aliases": ["k"] }, "dryRun": { "type": "boolean", diff --git a/projects/build-env/src/plugin/README.md b/projects/build-env/src/plugin/README.md new file mode 100644 index 00000000..b0f0db44 --- /dev/null +++ b/projects/build-env/src/plugin/README.md @@ -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` diff --git a/projects/build-env/src/plugin/build-env.plugin.ts b/projects/build-env/src/plugin/build-env.plugin.ts index 7be15d06..b0fd1d7c 100644 --- a/projects/build-env/src/plugin/build-env.plugin.ts +++ b/projects/build-env/src/plugin/build-env.plugin.ts @@ -180,9 +180,10 @@ function verdaccioTargets( > & StartVerdaccioOptions ): Record { - const { name: environmentProject } = projectConfig; - const { environmentsDir, ...verdaccioOptions } = options; - const environmentDir = join(environmentsDir, environmentProject); + const { name: envProject } = projectConfig; + const { environmentsDir, ...startVerdaccioOptions } = options; + const environmentDir = join(environmentsDir, envProject); + return { [DEFAULT_START_VERDACCIO_TARGET]: { // @TODO: consider using the executor function directly to reduce the number of targets @@ -192,14 +193,14 @@ function verdaccioTargets( port: uniquePort(), storage: join(environmentDir, 'storage'), clear: true, - ...verdaccioOptions, + ...startVerdaccioOptions, }, }, [DEFAULT_STOP_VERDACCIO_TARGET]: { executor: '@push-based/build-env:kill-process', options: { filePath: join(environmentsDir, VERDACCIO_REGISTRY_JSON), - ...verdaccioOptions, + ...startVerdaccioOptions, }, }, }; @@ -209,9 +210,9 @@ function getEnvTargets( projectConfig: ProjectConfiguration, options: NormalizedCreateNodeOptions['environments'] ): Record { - const { name: environmentProject } = projectConfig; + const { name: envProject } = projectConfig; const { environmentsDir } = options; - const environmentRoot = join(environmentsDir, environmentProject); + const environmentRoot = join(environmentsDir, envProject); return { [DEFAULT_BOOTSTRAP_TARGET]: { executor: '@push-based/build-env:bootstrap',