Stakcss

Stakcss takes a "stak" of files or data, runs them through a "stak" of bundlers (not included), and outputs bundled data, optionally saved to disk. Stakcss works similarly to tools like webpack, rollup, and postcss. The primary difference is that, where webpack and rollup bundle JavaScript, postcss compiles stylesheets, Stakcss can bundle or compile any type of file or content. Alone Stakcss doesn't do much, but in concert with bundlers it can do almost anything your heart desires.

Environment support

| Node | CLI | UMD | ES Module | Browser | |:------:|:-----:|:-----:|:---------:|:---------:| | ✔ | ✔ | x | x | x |

Install

npm install @brikcss/stakcss --save-dev

Terminology

Just to be clear:

• Stakcss: This bundler tool.
• bundler: A function which bundles a "stak" of files or content chunks.
• stak (as a noun): A "stack" of source files or content chunks to be bundled.
• bundle (as a noun): The resulting/bundled/compiled file or content from being run through Stakcss.
• bundle / stak (as a verb): The process of bundling/compiling staks into bundles.

Usage

Stakcss provides an API to run files or content through a series of bundlers. See below for creating a bundler. You may bundle a stak in Node or the command line:

• Node:

  const stak = require('@brikcss/stakcss');
  stak(options);

• CLI:

  stak <source files> [options]
  # or:
  node node_modules/.bin/stak <source files> [options]

Options

• source {String | Array | Glob} Source file paths.

• content {String} Source content.

• output {String} Output path. Note: If this is directory (either '/' as last character or an actual directory), OR if it contains [name] or [ext], then stakEachFile is automatically set to true and each file is treated as its own stak. [name] and [ext] provide the template for the output path. See stakEachFile for more details.

• bundlers {Array | String} List of bundlers to run the stak through. A {String} should be a comma-separated list. Each bundler can be any of the following:

  • {String} path to node module, which is required like any other node module.
  • {Function} (via Node or config file) which is run on each stak.
  • {Object} (via Node or config file) where:
    • bundler.run is the function to be run on each stak.
    • bundler.* can be provided by user for bundler configuration. The bundler object is passed to each stak (see creating a bundler).

  Note: Stakcss Bundler module names should be prefixed with stakcss-bundler-. For convenience, when referencing bundlers by name in the bundlers setting, you may optionally remove stakcss-bundler- from the name and Stakcss will still pick the module up. For example: bundlers: ['@brikcss/stakcss-bundler-copy'] and bundlers: ['@brikcss/copy'] will both pick run the @brikcss/stakcss-bundler-copy bundler.

• root {String} Source paths will be output relative to this directory.

• cwd {String} Current working directory. Affects bundler path resolution and default search path for the config file.

• rename {Function} (via Node or config file) Callback to allow user to rename output files. Useful when output is a directory.

• config {String} Path to config file. You can also use the shorthand syntax to set the config path and profiles to run at the same time. For example:

  stak --config=<path>:<profiles>

• profiles {String | Array} The config file can be set up to run multiple "profiles". In this case, each property name in the config file is a config profile. This option is passed to tell Stakcss which profile(s) to run. An array or comma-separated list will run multiple profiles. Or setting this property to all will run all profiles.

  stak --config=<path> --profiles=<profiles>

  # Run all profiles in the config file.
  stak --config=<path> --profiles=all

  You may also use the shorthand version with the config option as follows:

  stak --config=<path>:<profiles>

• id {String} ID or name of stak, used in log notifications. Defaults to profile property name, if exists, or the profile index.

• stakEachFile {Boolean} Whether to treat each file as its own stak. This option is automatically set to true if:

  • output ends with /.
  • output is a directory.
  • output contains [name].

  output path template: When stakEachFile is true and output exists, Stakcss replaces [name] and [ext] with source file path's name and ext. If [name] is not found in output, output is set to path.join(output, '[name].[ext]').

• watch {Boolean} Watch source file paths and "restak" when they change.

• watchPaths {Glob} Additional path(s) to watch when running the watcher. These paths do not get bundled, but when they change they will trigger a rebundle. It may be useful to include files in the watcher that the source files depend on.

Note: Some options, as noted above, are not available via the CLI unless you use a config file.

Creating a bundler

Creating a bundler is easy. To illustrate, here is a simple bundler:

const fs = require('fs-extra');

module.exports = (config = {}, bundler = {}) => {
	if (!config.content) {
		config.source.forEach(filepath => config.content += fs.readFileSync(filepath, 'utf8'));
	}
	return config;
};

This bundler copies file content from config.source to config.content, which Stakcss will later output to config.output. Simple enough, but it paints the picture. Note the following:

• config is the user's config object and contains the list of accepted options.
• bundler is optionally provided by the user and can be anything. It is intended to pass settings to each individual bundler.

Rules for creating a bundler

1. Stakcss global config is provided via config. Bundler specific config is provided via bundler. Except for config.content and config.sourceMap, these should generally not be modified.
2. Important: If config.content does not exist:
   1. Use config.source to get source content.
   2. Modify it to your heart's content.
   3. Save it to config.content.
3. You must return the config object with the newly bundled / transformed config.content.
4. You can optionally return a Promise. Stakcss will keep bundler results in order.
5. config.sourceMap is for use with sourcemaps.