@storm-software/workspace-tools NPM

!IMPORTANT This repository, and the apps, libraries, and tools contained within, is still in it's initial development phase. As a result, bugs and issues are expected with it's usage. When the main development phase completes, a proper release will be performed, the packages will be availible through NPM (and other distributions), and this message will be removed. However, in the meantime, please feel free to report any issues you may come across.

Storm Workspace Tools

A package containing tools for managing a Storm workspace. It includes various Nx generators and executors for common development tasks.

This library was generated with Nx.

Installing

Using pnpm:

pnpm add -D @storm-software/workspace-tools

npm install -D @storm-software/workspace-tools

yarn add -D @storm-software/workspace-tools

Executors

The following executors are available in this package to invoke common tasks for the workspace's projects:

Tsup Builder

Run a build on the project using ESBuild with a patched tsup configuration

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:tsup

Please note: The tsup executor should be included in the desired projects's project.json file.All required options must be included in the options property of the json.

Options

The following executor options are available:

Option	Type	Description	Default
entry	`string`	The path to the entry file, relative to project.	"{sourceRoot}/index.ts"
outputPath	`string`	The output path of the generated files.	"dist/{projectRoot}"
tsConfig *	`string`	The path to the `tsconfig.json` file.	"{projectRoot}/tsconfig.json"
additionalEntryPoints	`string[]`	List of additional entry points.	`[]`
external	`string[]`	Mark one or more module as external. Can use * wildcards, such as *.png.
bundle	`boolean`	Whether to bundle the main entry point and additional entry points. Set to false to keep individual output files.	`true`
watch	`boolean`	Enable re-building when files change.
assets	`array`	List of static assets.	`[]`
clean	`boolean`	Remove previous output before build.	`true`
includeSrc	`boolean`	Should the source files be added to the distribution folder in an `src` directory.
metafile	`boolean`	Should a meta file be created for the build package	`true`
emitOnAll	`boolean`	Should each file contained in the package be emitted individually.
generatePackageJson	`boolean`	Should a package.json file be generated in the output folder or should the existing one be copied in.	`true`
splitting	`boolean`	Should the build process preform code-splitting?	`true`
treeshake	`boolean`	Should the build process tree-shake to remove unused code?	`true`
format	`string[]`	The output format for the generated JavaScript files. There are currently three possible values that can be configured: iife, cjs, and esm.	`[]`
debug	`boolean`	Should output be unminified with source mappings.
platform *	"browser" \| "neutral" \| "node" \| "worker"	Platform target for outputs.	"neutral"
banner *	`string`	A short heading added to the top of each typescript file added in the output folder's `src` directory.	"This code was developed by Storm Software (https://stormsoftware.com) and is licensed under the Apache License 2.0."
minify	`boolean`	Should the build process minify the output files?
verbose	`boolean`	Should write extra log outputs with details from the executor.
skipNativeModulesPlugin	`boolean`	Should we skip adding the Native Node Modules ESBuild plugin.
useJsxModule	`boolean`	Should the build process use the `jsx` module for JSX support?
shims	`boolean`	Should the build process add shims for node.js modules that are not available in the browser?
define	`object`	Define global constants that can be used in the source code. The value will be converted into a stringified JSON.
env	`object`	Define environment variables that can be used in the source code. The value will be converted into a stringified JSON.
apiReport	`boolean`	Should API Extractor generate an API Report file.	`true`
docModel	`boolean`	Should API Extractor generate an Doc Model markdown file.	`true`
tsdocMetadata	`boolean`	Should API Extractor generate an TSDoc Metadata file.	`true`
options	`object`	Additional options to pass to tsup. See https://paka.dev/npm/tsup@7.2.0/api#d35d54aca71eb26e.
plugins	`object[]`	List of ESBuild plugins to use during processing	`[]`

Please note: Option names followed by * above are required, and must be provided to run the executor.

Neutral TypeScript Builder

Runs a neutral platform TypeScript build

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:tsup-neutral

Please note: The tsup-neutral executor should be included in the desired projects's project.json file.

Node TypeScript Builder

Runs a node platform TypeScript build

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:tsup-node

Please note: The tsup-node executor should be included in the desired projects's project.json file.

Options

The following executor options are available:

Option	Type	Description	Default
transports	`string[]`		`[]`

Browser TypeScript Builder

Runs a browser platform TypeScript build

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:tsup-browser

Please note: The tsup-browser executor should be included in the desired projects's project.json file.

Typia Generate Executor

Run the Typia generator to create runtime type validators

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:typia

Please note: The typia executor should be included in the desired projects's project.json file.All required options must be included in the options property of the json.

Options

The following executor options are available:

Option	Type	Description	Default
entryPath *	`string`	The path of the typescript files using `typia`.	"{sourceRoot}"
outputPath *	`string`	The output path of the generated files.	"{sourceRoot}/generated/typia"
tsConfig *	`string`	The path to the `tsconfig.json` file.	"{projectRoot}/tsconfig.json"
clean	`boolean`	Remove previous output before build.	`true`

Please note: Option names followed by * above are required, and must be provided to run the executor.

Npm Publish executor

Publish a package to the NPM registry - DO NOT INVOKE DIRECTLY WITH `nx run`. Use `nx release publish` instead.

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:npm-publish

Please note: The npm-publish executor should be included in the desired projects's project.json file.All required options must be included in the options property of the json.

Options

The following executor options are available:

Option	Type	Description	Default
packageRoot	`string`	The root directory of the directory (containing a manifest file at its root) to publish. Defaults to the project root.
registry *	`string`	The registry to publish the package to.	"https://registry.npmjs.org/"
tag	`string`	The distribution tag to apply to the published package.
dryRun	`boolean`	Whether to run the command without actually publishing the package to the registry.

Please note: Option names followed by * above are required, and must be provided to run the executor.

Cargo Publish executor

Publish a package to the crates.io registry - DO NOT INVOKE DIRECTLY WITH `nx run`. Use `nx release publish` instead.

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:cargo-publish

Please note: The cargo-publish executor should be included in the desired projects's project.json file.

Options

The following executor options are available:

Option	Type	Description	Default
packageRoot	`string`	The root directory of the directory (containing a manifest file at its root) to publish. Defaults to the project root.
dryRun	`boolean`	Whether to run the command without actually publishing the package to the registry.

Rolldown Builder

An executor used by Storm Software to run the Rolldown build process

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:rolldown

Please note: The rolldown executor should be included in the desired projects's project.json file.All required options must be included in the options property of the json.

Options

The following executor options are available:

Option	Type	Description	Default
entry	`string`	The path to the entry file, relative to project.	"{sourceRoot}/index.ts"
outputPath	`string`	The output path of the generated files.	"dist/{projectRoot}"
tsConfig *	`string`	The path to the `tsconfig.json` file.	"{projectRoot}/tsconfig.json"
additionalEntryPoints	`string[]`	List of additional entry points.	`[]`
watch	`boolean`	Enable re-building when files change.
assets	`array`	List of static assets.	`[]`
clean	`boolean`	Remove previous output before build.	`true`
includeSrc	`boolean`	Should the source files be added to the distribution folder in an `src` directory.
generatePackageJson	`boolean`	Should a package.json file be generated in the output folder or should the existing one be copied in.	`true`
debug	`boolean`	Should output be unminified with source mappings.
platform *	"browser" \| "neutral" \| "node" \| "worker"	Platform target for outputs.	"neutral"
banner *	`string`	A short heading added to the top of each typescript file added in the output folder's `src` directory.	"This code was developed by Storm Software (https://stormsoftware.com) and is licensed under the Apache License 2.0."
minify	`boolean`	Should the build process minify the output files?
verbose	`boolean`	Should write extra log outputs with details from the executor.
plugins	`object[]`	List of Rollup plugins to use during processing	`[]`

Please note: Option names followed by * above are required, and must be provided to run the executor.

Unbuild Builder

An executor used by Storm Software to run the Unbuild build process

Example

This executor can be used by executing the following in a command line utility:

nx run my-project:unbuild

Please note: The unbuild executor should be included in the desired projects's project.json file.All required options must be included in the options property of the json.

Options

The following executor options are available:

Option	Type	Description	Default
entry	`string`	The path to the entry file, relative to project.	"{sourceRoot}/index.ts"
outputPath	`string`	The output path of the generated files.	"dist/{projectRoot}"
tsConfig *	`string`	The path to the `tsconfig.json` file.	"{projectRoot}/tsconfig.json"
additionalEntryPoints	`string[]`	List of additional entry points.	`[]`
watch	`boolean`	Enable re-building when files change.
assets	`array`	List of static assets.	`[]`
clean	`boolean`	Remove previous output before build.	`true`
includeSrc	`boolean`	Should the source files be added to the distribution folder in an `src` directory.
debug	`boolean`	Should output be unminified with source mappings.
minify	`boolean`	Should the build process minify the output files?
verbose	`boolean`	Should write extra log outputs with details from the executor.
plugins	`object[]`	List of Rollup plugins to use during processing	`[]`

Please note: Option names followed by * above are required, and must be provided to run the executor.

Generators

The following generators are available with this package to assist in workspace management:

Init Storm Workspace Plugin

Init Storm Workspace Plugin.

Options

The following executor options are available:

Option	Type	Description	Default
skipFormat	`boolean`	Skip formatting files.

Workspace Preset

Create a Storm workspace with all of the required files and recommended packages installed.

Examples

This generator can be used by executing the following examples in a command line utility:

Generate a storm workspace with:

name: example-repo
namespace: storm-software
organization: storm-software
repositoryUrl: https://github.com/storm-software/example-repo

nx g @storm-software/workspace-tools:preset --name 'example-repo'

Generate a storm workspace with:

name: example-repo
namespace: example
repositoryUrl: https://github.com/storm-software/example-repo

nx g @storm-software/workspace-tools:preset --name 'example-repo' --namespace 'example'

Generate a storm workspace with:

name: example-repo
namespace: example
organization: example-org
description: An example workspace
repositoryUrl: https://github.com/example-org/example-repo

nx g @storm-software/workspace-tools:preset --name 'example-repo' --namespace 'example' --organization 'example-org' --description 'An example workspace'

Options

The following executor options are available:

Option	Type	Description	Default
name *	`string`	The name of the workspace root.
organization *	`string`	The organization that owns the workspace.	"storm-software"
namespace	`string`	The npm scope used for the workspace. Defaults to the organization name.
includeApps *	`boolean`	Should a separate `apps` folder be created for this workspace (if Yes: `apps` and `libs` folders will be added, if No: `packages` folders will be added)?
description	`string`	The description of the workspace to use in the package.json and README.md files.
repositoryUrl	`string`	The URL of the workspace in GitHub. Defaults to https://github.com/{organization}/{name}
includeRust	`boolean`	Should the workspace include Rust support?
nxCloud	`boolean`	Should distributed caching with Nx Cloud be enabled for the workspace?
mode *	"light" \| "dark"	Which client mode should be used for the Nx Task Runner?	"dark"
packageManager	"npm" \| "yarn" \| "pnpm"	What package manager is used for the workspace?	"pnpm"

Please note: Option names followed by * above are required, and must be provided to run the executor.

Add Node Library

Create a new NodeJs TypeScript library package in the Storm workspace

Options

The following executor options are available:

Option	Type	Description	Default
name *	`string`	A name for the library.
description	`string`	The library used by Storm Software for building TypeScript applications.
directory *	`string`	A directory where the lib is placed.
projectNameAndRootFormat *	"as-provided" \| "derived"	Whether to generate the project name and root directory as provided (`as-provided`) or generate them composing their values and taking the configured layout into account (`derived`).
tags	`string`	Add tags to the library (used for linting).
strict	`boolean`	Whether to enable tsconfig strict mode or not.	`true`
publishable *	`boolean`	Generate a publishable library.
importPath *	`string`	The library name used to import it, like @storm-software/my-awesome-lib. Required for publishable library.
buildable *	`boolean`	Generate a buildable library.	`true`
setParserOptionsProject	`boolean`	Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons.
rootProject	`boolean`	Is the current project the root project in the workspace.

Please note: Option names followed by * above are required, and must be provided to run the executor.

Configuration Schema Creator

Create a StormConfig JSON schema based on the workspace's project configurations

Options

The following executor options are available:

Option	Type	Description	Default
outputFile *	`string`	The file path where the schema json will be written (relative to the workspace root)	"./storm.schema.json"

Please note: Option names followed by * above are required, and must be provided to run the executor.

Add Neutral Library

Create a new Neutral TypeScript library package in the Storm workspaces

Options

The following executor options are available:

Option	Type	Description	Default
name *	`string`	A name for the library.
description	`string`	The library used by Storm Software for building TypeScript applications.
directory *	`string`	A directory where the lib is placed.
projectNameAndRootFormat *	"as-provided" \| "derived"	Whether to generate the project name and root directory as provided (`as-provided`) or generate them composing their values and taking the configured layout into account (`derived`).
tags	`string`	Add tags to the library (used for linting).
strict	`boolean`	Whether to enable tsconfig strict mode or not.	`true`
publishable *	`boolean`	Generate a publishable library.
importPath *	`string`	The library name used to import it, like @storm-software/my-awesome-lib. Required for publishable library.
buildable *	`boolean`	Generate a buildable library.	`true`
setParserOptionsProject	`boolean`	Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons.
rootProject	`boolean`	Is the current project the root project in the workspace.

Please note: Option names followed by * above are required, and must be provided to run the executor.

Add browser Library

Create a new browser TypeScript library package in the Storm workspace

Options

The following executor options are available:

Option	Type	Description	Default
name *	`string`	A name for the library.
description	`string`	The library used by Storm Software for building TypeScript applications.
directory *	`string`	A directory where the lib is placed.
projectNameAndRootFormat *	"as-provided" \| "derived"	Whether to generate the project name and root directory as provided (`as-provided`) or generate them composing their values and taking the configured layout into account (`derived`).
tags	`string`	Add tags to the library (used for linting).
strict	`boolean`	Whether to enable tsconfig strict mode or not.	`true`
publishable *	`boolean`	Generate a publishable library.
importPath *	`string`	The library name used to import it, like @storm-software/my-awesome-lib. Required for publishable library.
buildable *	`boolean`	Generate a buildable library.	`true`
setParserOptionsProject	`boolean`	Whether or not to configure the ESLint `parserOptions.project` option. We do not do this by default for lint performance reasons.
rootProject	`boolean`	Is the current project the root project in the workspace.

Please note: Option names followed by * above are required, and must be provided to run the executor.

design-tokens

Generate design tokens code using a Token Studio export

Storm Release Version Generator

The release version generator used in Storm Workspaces

Options

The following executor options are available:

Option	Type	Description	Default
projects *	`object[]`	The ProjectGraphProjectNodes being versioned in the current execution.
projectGraph *	`object`	ProjectGraph instance
specifier	`string`	Exact version or semver keyword to apply to the selected release group. Overrides specifierSource.
releaseGroup *	`object`	The resolved release group configuration, including name, relevant to all projects in the current execution.
specifierSource	"prompt" \| "conventional-commits"	Which approach to use to determine the semver specifier used to bump the version of the project.	"conventional-commits"
preid	`string`	The optional prerelease identifier to apply to the version, in the case that specifier has been set to prerelease.
packageRoot	`string`	The root directory of the directory (containing a manifest file at its root) to publish. Defaults to the project root
currentVersionResolver	"registry" \| "disk" \| "git-tag"	Which approach to use to determine the current version of the project.	"disk"
currentVersionResolverMetadata	`object`	Additional metadata to pass to the current version resolver.	`[object Object]`

Please note: Option names followed by * above are required, and must be provided to run the executor.

Building

Run nx build workspace-tools to build the library.

Running unit tests

Run nx test workspace-tools to execute the unit tests via Jest.

Storm Workspaces

Storm workspaces are built using Nx, a set of extensible dev tools for monorepos, which helps you develop like Google, Facebook, and Microsoft. Building on top of Nx, the Open System provides a set of tools and patterns that help you scale your monorepo to many teams while keeping the codebase maintainable.

Roadmap

See the open issues for a list of proposed features (and known issues).

Top Feature Requests (Add your votes using the 👍 reaction)
Top Bugs (Add your votes using the 👍 reaction)
Newest Bugs

Support

Reach out to the maintainer at one of the following places:

License

This project is licensed under the Apache License 2.0. Feel free to edit and distribute this template as you like.

See LICENSE for more information.

Changelog

This project adheres to Semantic Versioning. Every release, along with the migration instructions, is documented in the CHANGELOG file

Contributing

First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please try to create bug reports that are:

Reproducible. Include steps to reproduce the problem.
Specific. Include as much detail as possible: which version, what environment, etc.
Unique. Do not duplicate existing opened issues.
Scoped to a Single Bug. One bug per report.

Please adhere to this project's code of conduct.

You can use markdownlint-cli to check for common markdown style inconsistency.

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Storm Software is an open source software development organization and creator of Acidic, StormStack and StormCloud.

Our mission is to make software development more accessible. Our ideal future is one where anyone can create software without years of prior development experience serving as a barrier to entry. We hope to achieve this via LLMs, Generative AI, and intuitive, high-level data modeling/programming languages.