@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 available 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

Storm Workspace Tools

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

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:

Typia Executor

A type definition for a Typia executor schema

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
outputPath *	`string`	The output path for the build	"{sourceRoot}/generated/typia"
entry *	`string[]`	The entry file or files to build	`[]`
tsconfig *	`string`	The path to the tsconfig file	"{projectRoot}/tsconfig.json"
clean	`boolean`	Clean the output directory before building	`true`

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

ESBuild Executor

A type definition for an ESBuild executor schema

Example

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

nx run my-project:esbuild

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The output path for the build	"dist/{projectRoot}"
entry	`string[]`	The entry file or files to build	`[]`
tsconfig	`string`	The path to the tsconfig file	"{projectRoot}/tsconfig.json"
bundle	`boolean`	Bundle the output
minify	`boolean`	Minify the output
debug	`boolean`	Debug the output
sourcemap	`boolean`	Generate a sourcemap
silent	`boolean`	Should the build run silently - only report errors back to the user
target	"es3" \| "es5" \| "es6" \| "es2015" \| "es2016" \| "es2017" \| "es2018" \| "es2019" \| "es2020" \| "es2021" \| "es2022" \| "es2023" \| "es2024" \| "esnext" \| "node12" \| "node14" \| "node16" \| "node18" \| "node20" \| "node22" \| "browser" \| "chrome58" \| "chrome59" \| "chrome60"	The target to build	"esnext"
format	"cjs" \| "esm" \| "iife"	The format to build	"esm"
platform	"neutral" \| "node" \| "browser"	The platform to build	"neutral"
external	`any[]`	The external dependencies	`[]`
define	`object`	The define values	`[object Object]`
env	`object`	The environment variable values	`[object Object]`

Unbuild Executor

A type definition for a unbuild executor schema

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
outputPath	`string`	The output path for the build
entry *	`string[]`	The directory to use as input for the build	`[]`
tsconfig	`string`	The path to the tsconfig file	"{projectRoot}/tsconfig.json"
bundle	`boolean`	Bundle the output
minify	`boolean`	Minify the output
debug	`boolean`	Debug the output
sourcemap	`boolean`	Generate a sourcemap
silent	`boolean`	Should the build run silently - only report errors back to the user
target	"es3" \| "es5" \| "es6" \| "es2015" \| "es2016" \| "es2017" \| "es2018" \| "es2019" \| "es2020" \| "es2021" \| "es2022" \| "es2023" \| "es2024" \| "esnext" \| "node12" \| "node14" \| "node16" \| "node18" \| "node20" \| "node22" \| "browser" \| "chrome58" \| "chrome59" \| "chrome60"	The target to build	"esnext"
format	`string[]`	The format to build	`[]`
platform	"neutral" \| "node" \| "browser"	The platform to build	"neutral"
external	`any[]`	The external dependencies	`[]`
define	`object`	The define values	`[object Object]`
env	`object`	The environment variable values	`[object Object]`
name *	`string`	The name of the project/build	"{projectName}"
treeShaking	`boolean`	Enable tree shaking	`true`
watch	`boolean`	Watch for changes
clean	`boolean`	Clean the output directory before building	`true`
stub	`boolean`	Stub the output
buildOnly	`boolean`	Should the build process skip generating a package.json and copying assets
watchOptions	`object`	Watch options	`[object Object]`
stubOptions	`object`	Stub options	`[object Object]`
dependencies	`string[]`	The dependencies to install
peerDependencies	`string[]`	The peer dependencies to install
devDependencies	`string[]`	The dev dependencies to install
alias	`object`	The alias to use	`[object Object]`
replace	`object`	The replace to use	`[object Object]`
rollup	`object`	The rollup options	`[object Object]`

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

Clean Package Executor

The clean package executor is responsible for removing unnecessary files and fields from a distributable package to make it as light as possible (for scenarios like edge computing, limited memory environments, etc.)

Example

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

nx run my-project:clean-package

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The path to the output	"dist/{projectRoot}"
packageJsonPath	`string`	The path to the package.json that will be modified	"{outputPath}/package.json"
ignoredFiles	`string`	The files to ignore
fields	`string`	The fields to include	""
cleanReadMe	`boolean`	Clean the read me	`true`
cleanComments	`boolean`	Clean the comments	`true`

Size Limit Executor

A type definition for a Size Limit executor schema

Example

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

nx run my-project:size-limit

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The output path for the build	"dist/{projectRoot}"
entry	`string[]`	The path to the entry file

Npm Publish Executor

A type definition for a Npm Publish executor schema

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.

Options

The following executor options are available:

Option	Type	Description	Default
packageRoot	`string`	The path to the package root
registry	`string`	The registry to publish to	"https://registry.npmjs.org/"
tag	`string`	The tag to publish with	"latest"
version	`string`	The version to publish. If not provided, the version from package.json will be used
otp	`number`	The one time password
dryRun	`boolean`	Perform a dry run
firstRelease	`boolean`	Publish the first release

Cargo Publish Executor

A type definition for a Cargo/rust Publish executor schema

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
outputPath	`string`	The output path for the build	"dist/{projectRoot}"
package	`string`	The path to the Cargo.toml file	"{projectRoot}/Cargo.toml"
toolchain	"stable" \| "beta" \| "nightly"	The type of toolchain to use for the build	"stable"
target	`string`	The target to build
allTargets	`boolean`	Build all targets
profile	`string`	The profile to build
release	`boolean`	Build in release mode
features	`string`	The features to build
allFeatures	`boolean`	Build all features
registry	`string`	The registry to publish to
packageRoot	`string`	The path to the package root
dryRun	`boolean`	Perform a dry run

Cargo Build Executor

A type definition for a Cargo/rust build executor schema

Example

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

nx run my-project:cargo-build

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The path to the output directory
package	`string`	The path to the Cargo.toml file	"{projectRoot}/Cargo.toml"
toolchain	"stable" \| "beta" \| "nightly"	The type of toolchain to use for the build	"stable"
target	`string`	The target to build
allTargets	`boolean`	Build all targets
profile	`string`	The profile to build
release	`boolean`	Build in release mode
features	`string`	The features to build
allFeatures	`boolean`	Build all features

Cargo Check Executor

A type definition for a Cargo/rust check executor schema

Example

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

nx run my-project:cargo-check

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The output path for the build	"dist/{projectRoot}"
package	`string`	The path to the Cargo.toml file	"{projectRoot}/Cargo.toml"
toolchain	"stable" \| "beta" \| "nightly"	The type of toolchain to use for the build	"stable"
target	`string`	The target to build
allTargets	`boolean`	Build all targets
profile	`string`	The profile to build
release	`boolean`	Build in release mode
features	`string`	The features to build
allFeatures	`boolean`	Build all features

Cargo Format Executor

A type definition for a Cargo/rust format executor schema

Example

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

nx run my-project:cargo-format

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The output path for the build	"dist/{projectRoot}"
package	`string`	The path to the Cargo.toml file	"{projectRoot}/Cargo.toml"
toolchain	"stable" \| "beta" \| "nightly"	The type of toolchain to use for the build	"stable"
target	`string`	The target to build
allTargets	`boolean`	Build all targets
profile	`string`	The profile to build
release	`boolean`	Build in release mode
features	`string`	The features to build
allFeatures	`boolean`	Build all features

Cargo Clippy Executor

A type definition for a Cargo/rust clippy executor schema

Example

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

nx run my-project:cargo-clippy

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The output path for the build	"dist/{projectRoot}"
package	`string`	The path to the Cargo.toml file	"{projectRoot}/Cargo.toml"
toolchain	"stable" \| "beta" \| "nightly"	The type of toolchain to use for the build	"stable"
target	`string`	The target to build
allTargets	`boolean`	Build all targets
profile	`string`	The profile to build
release	`boolean`	Build in release mode
features	`string`	The features to build
allFeatures	`boolean`	Build all features
fix	`boolean`	Automatically fix issues

Cargo Doc Executor

A type definition for a Cargo/rust documentation executor schema

Example

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

nx run my-project:cargo-doc

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

Options

The following executor options are available:

Option	Type	Description	Default
outputPath	`string`	The output path for the build	"dist/{projectRoot}"
package	`string`	The path to the Cargo.toml file	"{projectRoot}/Cargo.toml"
toolchain	"stable" \| "beta" \| "nightly"	The type of toolchain to use for the build	"stable"
target	`string`	The target to build
allTargets	`boolean`	Build all targets
profile	`string`	The profile to build
release	`boolean`	Build in release mode
features	`string`	The features to build
allFeatures	`boolean`	Build all features
lib	`boolean`	Generate documentation for the library	`[object Object]`
bins	`boolean`	Generate documentation for the bins	`[object Object]`
examples	`boolean`	Generate documentation for the examples	`[object Object]`
noDeps	`boolean`	Do not generate documentation for dependencies	`[object Object]`

Generators

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

Init Generator

A type definition for an init generator schema

Options

The following executor options are available:

Option	Type	Description	Default
skipFormat	`boolean`	Skip formatting the generated files

Preset Generator

A type definition for a preset generator schema

Options

The following executor options are available:

Option	Type	Description	Default
directory *	`string`	The directory to create the library in
name *	`string`	The name of the workspace
organization	`string`	The organization of the workspace	"storm-software"
includeApps	`boolean`	Include apps in the workspace	`true`
includeRust	`boolean`	Include Rust support in the workspace
namespace	`string`	The namespace of the workspace	"storm-software"
description	`string`	The description of the workspace
repositoryUrl	`string`	The URL of the repository
nxCloud	`string`	Nx Cloud configuration
mode	`string`	The mode of the Nx client
packageManager	"npm" \| "pnpm" \| "yarn" \| "bun"	The package manager to use	"pnpm"

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

Node Library Generator

A type definition for a NodeJs library generator schema

Options

The following executor options are available:

Option	Type	Description	Default
directory *	`string`	The directory to create the library in
name *	`string`	The name of the library
description	`string`	The description of the library
buildExecutor	`string`	The executor to use for building the library	"@storm-software/workspace-tools:unbuild"
platform	"node" \| "neutral"	The platform to target with the library	"node"
importPath	`string`	The import path for the library
tags	`string`	The tags for the library
unitTestRunner	"jest" \| "vitest" \| "none"	The unit test runner to use
testEnvironment	"jsdom" \| "node"	The test environment to use
pascalCaseFiles	`boolean`	Use PascalCase for file names
strict	`boolean`	Enable strict mode	`true`
publishable	`boolean`	Make the library publishable
buildable	`boolean`	Make the library buildable	`true`

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

Config Schema Generator

A type definition for a config schema generator schema

Options

The following executor options are available:

Option	Type	Description	Default
directory	`string`	The directory to create the library in
outputFile	`string`	The file to write the schema to	"{workspaceRoot}/storm-workspace.schema.json"

Neutral Library Generator

A type definition for a neutral library generator schema

Options

The following executor options are available:

Option	Type	Description	Default
directory *	`string`	The directory to create the library in
name *	`string`	The name of the library
description	`string`	The description of the library
buildExecutor	`string`	The executor to use for building the library	"@storm-software/workspace-tools:unbuild"
platform	"neutral"	The platform to target with the library	"neutral"
importPath	`string`	The import path for the library
tags	`string`	The tags for the library
unitTestRunner	"jest" \| "vitest" \| "none"	The unit test runner to use
testEnvironment	"jsdom" \| "node"	The test environment to use
pascalCaseFiles	`boolean`	Use PascalCase for file names
strict	`boolean`	Enable strict mode	`true`
publishable	`boolean`	Make the library publishable
buildable	`boolean`	Make the library buildable	`true`

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

Browser Library Generator

A type definition for a browser library generator schema

Options

The following executor options are available:

Option	Type	Description	Default
directory *	`string`	The directory to create the library in
name *	`string`	The name of the library
description	`string`	The description of the library
buildExecutor	`string`	The executor to use for building the library	"@storm-software/workspace-tools:unbuild"
platform	"browser" \| "neutral"	The platform to target with the library	"browser"
importPath	`string`	The import path for the library
tags	`string`	The tags for the library
unitTestRunner	"jest" \| "vitest" \| "none"	The unit test runner to use
testEnvironment	"jsdom" \| "node"	The test environment to use
pascalCaseFiles	`boolean`	Use PascalCase for file names
strict	`boolean`	Enable strict mode	`true`
publishable	`boolean`	Make the library publishable
buildable	`boolean`	Make the library buildable	`true`

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

Release Version Generator

A type definition for a release version generator schema

Options

The following executor options are available:

Option	Type	Description	Default
projects *	`object[]`	The projects to release
releaseGroup *	`object`	The release group	`[object Object]`
projectGraph *	`object`	The project graph	`[object Object]`
specifier *	`string`	The specifier
specifierSource	`string`	The specifier source
preid	`string`	The preid
packageRoot	`string`	The package root
currentVersionResolver	`string`	The current version resolver	"git-tag"
currentVersionResolverMetadata	`object`	The current version resolver metadata	`[object Object]`
fallbackCurrentVersionResolver	`string`	The fallback current version resolver	"disk"
firstRelease	`boolean`	Release the first version
versionPrefix	"" \| "auto" \| "~" \| "^" \| "="	The version prefix
skipLockFileUpdate	`boolean`	Skip lock file update
installArgs	`string`	The install arguments
installIgnoreScripts	`boolean`	Ignore scripts
conventionalCommitsConfig	`object`	The conventional commits config	`[object Object]`
deleteVersionPlans	`boolean`	Delete version plans
updateDependents	`string`	Update dependents
logUnchangedProjects	`boolean`	Log unchanged projects
preserveLocalDependencyProtocols	`boolean`	Preserve local dependency protocols

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.

Join us on Discord to chat with the team, receive release notifications, ask questions, and get involved.

If this sounds interesting, and you would like to help us in creating the next generation of development tools, please reach out on our website or join our Slack channel!

Table of Contents

Storm Workspace Tools

Installing

Executors

Typia Executor

Example

Options

ESBuild Executor

Example

Options

Unbuild Executor

Example

Options

Clean Package Executor

Example

Options

Size Limit Executor

Example

Options

Npm Publish Executor

Example

Options

Cargo Publish Executor

Example

Options

Cargo Build Executor

Example

Options

Cargo Check Executor

Example

Options

Cargo Format Executor

Example

Options

Cargo Clippy Executor

Example

Options

Cargo Doc Executor

Example

Options

Generators

Init Generator

Options

Preset Generator

Options

Node Library Generator

Options

Config Schema Generator

Options

Neutral Library Generator

Options

Browser Library Generator

Options

Release Version Generator

Options

Building

Running unit tests

Storm Workspaces

Roadmap

Support

License

Changelog

Contributing

Contributors