Shanzhai

A crude, plugin-based build system built upon NodeJS.

NPM packages

Plugins

For the most part, software built using Shanzhai is configured simply by adding NPM dependencies upon plugins (e.g. npm install --save-dev @shanzhai/read-type-script-files-plugin). A plugin will typically read information from one or more files or stores, apply a transformation, then write the results to one or more files or stores.

Take note of and install any peer dependencies recommended upon installation of these packages.

Name	Version	Description	Published
@shanzhai/collect-svg-defs-plugin		A Shanzhai plugin which collects SVG defs, outputting the results to the Pug locals store, the TypeScript globals store and the TypeScript source store.	✔️
@shanzhai/compile-type-script-plugin		A Shanzhai plugin while compiles the entire store of parsed TypeScript, storing the resulting Javascript in corresponding source store.	✔️
@shanzhai/convert-svg-documents-to-defs-plugin		A Shanzhai plugin which converts the contents of the minified SVG store to defs, outputting them to the defs store.	✔️
@shanzhai/es5-type-script-compiler-options-plugin		A Shanzhai plugin which loads a set of TypeScript compiler options for ES5.	✔️
@shanzhai/favicons-plugin		A Shanzhai plugin which minifies HTML from the source store.	✔️
@shanzhai/html-header-pug-local-plugin		A Shanzhai plugin which converts the generated HTML headers to a Pug local.	✔️
@shanzhai/minify-html-plugin		A Shanzhai plugin which minifies HTML from the source store.	✔️
@shanzhai/minify-javascript-plugin		A Shanzhai plugin which minifies the Javascript from the source store, writing the resulting Javascript to the Pug locals store.	✔️
@shanzhai/minify-svg-plugin		A Shanzhai plugin which minifies SVG from the source store.	✔️
@shanzhai/output-type-script-compiler-options-plugin		A Shanzhai plugin which outputs the current TypeScript compiler options to the current working directory.	✔️
@shanzhai/output-zip-content-plugin		A Shanzhai plugin which outputs the content of the distributable zip to the dist/content subdirectory of the current working directory.	✔️
@shanzhai/output-zip-plugin		A Shanzhai plugin which outputs the distributable zip to the dist subdirectory of the current working directory.	✔️
@shanzhai/parse-favicons-options-plugin		A Shanzhai plugin which parses previously read favicons options.	✔️
@shanzhai/parse-pug-plugin		A Shanzhai plugin which parses Pug source.	✔️
@shanzhai/parse-type-script-plugin		A Shanzhai plugin which parses TypeScript source files.	✔️
@shanzhai/read-favicon-plugin		A Shanzhai plugin which reads the "favicon" file into the favicon store.	✔️
@shanzhai/read-favicons-options-plugin		A Shanzhai plugin which reads the "favicons-options.json" file into the favicons options source store.	✔️
@shanzhai/read-pug-files-plugin		A Shanzhai plugin which reads Pug files into the Pug source store.	✔️
@shanzhai/read-svg-files-plugin		A Shanzhai plugin which reads SVG files into the SVG source store.	✔️
@shanzhai/read-type-script-files-plugin		A Shanzhai plugin which reads TypeScript (*.ts) files into the TypeScript source store.	✔️
@shanzhai/render-pug-plugin		A Shanzhai plugin which renders parsed Pug, storing the results in the HTML source store. File extensions of ".pug" are automatically replaced with ".html".	✔️
@shanzhai/zip-plugin		A Shanzhai plugin which zips the generated content.	✔️

Command-Line Executables

These command-line executables can be ran using NPX (e.g. npx @shanzhai/production-cli).

Name	Version	Description	Published
@shanzhai/production-cli		A CLI tool which performs a one-off production build of the Shanzhai project in the current directory.	✔️
@shanzhai/watch-cli		A CLI tool which performs a build of the Shanzhai project in the current directory, watching for changes and rebuilding automatically.	✔️

For extending Shanzhai

These packages are only needed should you wish to extend Shanzhai itself.

Steps

Whenever a plugin is triggered, it generates a step.

Most are "action steps", which perform a single operation such as reading a file, compiling script or minifying mark-up.

Some are "aggregation steps", which allow multiple other steps to be executed in parallel or serial.

Name	Version	Description	Published
@shanzhai/collect-svg-defs-step		A Shanzhai step which collects a number of SVG defs into a single document, and generates TypeScript source which can be used to refer to those defs.	✔️
@shanzhai/compile-type-script-step		A Shanzhai step which compiles parsed TypeScript to Javascript.	✔️
@shanzhai/convert-json-to-type-script-step		A Shanzhai step which converts a JSON value to TypeScript source code for ambient declarations.	✔️
@shanzhai/convert-parsed-csv-to-struct-of-arrays-step		A Shanzhai step which converts a parsed CSV file to a "struct-of-arrays" format where each column is its own array.	✔️
@shanzhai/convert-svg-document-to-def-step		A Shanzhai step which converts a SVG document to a def to be embedded in another SVG document.	✔️
@shanzhai/copy-step		A Shanzhai step which copies an input to an output.	✔️
@shanzhai/create-directory-step		A Shanzhai step which ensures that a directory exists (as well as all of its parent directories).	✔️
@shanzhai/delete-from-keyed-store-step		A Shanzhai step which deletes a key/value from a keyed store.	✔️
@shanzhai/delete-step		A Shanzhai step which deletes a file or directory (including any child files or directories) if it exists.	✔️
@shanzhai/favicons-step		A Shanzhai step which converts an image to HTML headers and files representing favicons.	✔️
@shanzhai/minify-html-step		A Shanzhai step which minifies a HTML file.	✔️
@shanzhai/minify-javascript-step		A Shanzhai step which minifies a Javascript file.	✔️
@shanzhai/minify-step		A Shanzhai step which can be built upon to create recursive minification build steps.	✔️
@shanzhai/minify-svg-step		A Shanzhai step which minifies a SVG file.	✔️
@shanzhai/nop-step		A Shanzhai step which does nothing.	✔️
@shanzhai/parallel-step		A Shanzhai build step which runs any number of child build steps in parallel.	✔️
@shanzhai/parse-csv-step		A Shanzhai step which parses CSV files.	✔️
@shanzhai/parse-json-step		A Shanzhai step which parses JSON from a string.	✔️
@shanzhai/parse-pug-step		A Shanzhai step which parses Pug files.	✔️
@shanzhai/parse-type-script-step		A Shanzhai step which compiles parsed TypeScript.	✔️
@shanzhai/read-binary-file-step		A Shanzhai step which reads the content of a binary file.	✔️
@shanzhai/read-text-file-step		A Shanzhai step which reads the content of a UTF-8 encoded text file.	✔️
@shanzhai/render-pug-step		A Shanzhai step which renders parsed Pug files.	✔️
@shanzhai/serial-step		A Shanzhai build step which runs any number of child build steps in serial.	✔️
@shanzhai/stringify-json-step		A Shanzhai step which "stringifies" a JSON value to a string.	✔️
@shanzhai/validate-json-schema-step		A Shanzhai step which validates a JSON value against a JSON schema.	✔️
@shanzhai/write-file-step		A Shanzhai step which writes to a binary or UTF-8 encoded text file, creating it if it does not exist, or replacing it if it does.	✔️
@shanzhai/zip-step		A Shanzhai step which creates a zip file from a list of binary or UTF-8 encoded text files.	✔️

Inputs

An input provides a value to a step during its execution.

While some perform transformations, most simply provide a value. Inputs should not be performing complex or potentially risky operations.

Name	Version	Description	Published
@shanzhai/build-object-input		A Shanzhai input which builds an object from a number of other inputs.	✔️
@shanzhai/build-tsconfig-input		A Shanzhai input which converts TypeScript compiler options to JSON as would be found in a tsconfig.json file.	✔️
@shanzhai/concatenate-object-values-input		A Shanzhai input which concatenates the (string) values of an object returned by another input.	✔️
@shanzhai/constant-input		A Shanzhai input which provides a constant input to a build step.	✔️
@shanzhai/keyed-store-get-all-input		A Shanzhai input which reads all keys and values from a keyed store as an object.	✔️
@shanzhai/keyed-store-get-input		A Shanzhai input which reads a single value from a keyed store.	✔️
@shanzhai/keyed-store-get-keys-input		A Shanzhai input which reads all keys from a keyed store as an array of strings.	✔️
@shanzhai/merge-object-input		A Shanzhai input which builds an object by merging the objects retrieved by other inputs.	✔️
@shanzhai/stringify-json-input		A Shanzhai input which "stringifies" a value after retrieving it from an input.	✔️
@shanzhai/unkeyed-store-get-input		A Shanzhai input which reads the value of an unkeyed store.	✔️

Outputs

An output stores a value provided by a step during its execution.

As with inputs, most simply store a value. Only simple and fast transformations should be performed in outputs, and preferably none should be made at all.

Name	Version	Description	Published
@shanzhai/keyed-store-set-output		A Shanzhai output which sets a value in a keyed store.	✔️
@shanzhai/null-output		A Shanzhai output which discards any value it is given without taking further action.	✔️
@shanzhai/stringify-json-output		A Shanzhai output which "stringifies" a value before passing it to an output.	✔️
@shanzhai/unkeyed-store-set-output		A Shanzhai output which sets the value of an unkeyed store.	✔️
@shanzhai/wrap-in-object-output		A Shanzhai output which wraps a value in an object with a given key.	✔️

Stores

Stores are peer dependencies of plugins, and are used to pass data between them.

For example:

• A plugin to read TypeScript files from disk might write the read TypeScript into a keyed ephemeral store.
• A plugin might then read from that store to parse the files, writing the results to another keyed ephemeral store.
• Then, another plugin might collect all those parsed files to compile them, writing the result to an unkeyed ephemeral store.

Name	Version	Description	Published
@shanzhai/ephemeral-keyed-store		A keyed Shanzhai store which holds data in memory until the application closes.	✔️
@shanzhai/ephemeral-unkeyed-store		An unkeyed Shanzhai store which holds data in memory until the application closes.	✔️
@shanzhai/favicon-store		A Shanzhai store for the favicon image read from disk.	✔️
@shanzhai/favicons-options-source-store		A Shanzhai store for unparsed options for the "favicons" package.	✔️
@shanzhai/favicons-options-store		A Shanzhai store for options for the "favicons" package.	✔️
@shanzhai/html-header-store		A Shanzhai store for sets of HTML headers.	✔️
@shanzhai/html-source-store		A Shanzhai store for HTML source.	✔️
@shanzhai/javascript-source-store		A Shanzhai store for Javascript source files.	✔️
@shanzhai/minified-svg-store		A Shanzhai store for minified SVG files.	✔️
@shanzhai/parsed-pug-store		A Shanzhai store for parsed Pug.	✔️
@shanzhai/parsed-type-script-store		A Shanzhai store for parsed TypeScript source files.	✔️
@shanzhai/pug-local-store		A Shanzhai store for locals to be passed to Pug templates.	✔️
@shanzhai/pug-source-store		A Shanzhai store for Pug source.	✔️
@shanzhai/svg-def-store		A Shanzhai store for SVG defs.	✔️
@shanzhai/svg-source-store		A Shanzhai store for SVG source files.	✔️
@shanzhai/type-script-compiler-options-store		A Shanzhai store for TypeScript compiler options.	✔️
@shanzhai/type-script-global-store		A Shanzhai store for global variables to be included in TypeScript builds.	✔️
@shanzhai/type-script-source-store		A Shanzhai store for TypeScript source files.	✔️
@shanzhai/zip-content-store		A Shanzhai store for SVG defs.	✔️
@shanzhai/zip-store		A Shanzhai store for the distributable zip.	✔️

Other

These packages do not fall into any of the above categories.

Name	Version	Description	Published
@shanzhai/change-tracking-helpers		Helpers for tracking changes to files during a Shanzhai build.	✔️
@shanzhai/execution-helpers		Helpers which execute a tree of steps to perform a Shanzhai build.	✔️
@shanzhai/glob-compare-function		A comparison function for sorting glob patterns by priority.	✔️
@shanzhai/interfaces		TypeScript types used as interfaces between the various components of Shanzhai.	✔️
@shanzhai/planning-helpers		Helpers which generate a tree of steps to execute to perform a Shanzhai build.	✔️
@shanzhai/plugin-helpers		Helpers for searching for plugins during a Shanzhai build.	✔️
@shanzhai/resample		Adjust the sample rate of floating-point audio.	✔️

License