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/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-pug-plugin | A Shanzhai plugin which parses Pug source. | ||
@shanzhai/parse-type-script-plugin | A Shanzhai plugin which parses TypeScript source files. | ||
@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. | ||
@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/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/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/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/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/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. |