ideal is a collection of pre-existing tools for generating client assets, wrapped up in an easy to use CLI. It currently supports TypeScript and SASS. The tools used are as follows:

• webpack and node-sass for compilation.
• ~~jest and pupeteer for unit and integration tests.~~ Coming soon
• ~~ts-lint and stylelint for linting.~~ Coming soon

Getting Started

Install with npm:

npm install --save-dev ideal-tools

Install with yarn:

yarn add --dev ideal-tools

TypeScript v3.8 is a peerDependency of ideal, so ensure you have it setup with a root tsconfig.json and installed as a dependency of your project.

Basic Usage

There are currently two "tasks" provided, build:css and build:js. ideal uses a glob path to target files, and outputs, by default, in a relative directory: ./dist. This can be configured with a contextual config file, outlined below.

Try it out:

$ ideal build:js ./src/*.ts
$ ideal build:css ./src/*.scss

Configuration

You can configure each build task via CLI arguments, or with an ideal.config.js file, located relative to where ideal is being run from.

CLI Arguments

Arguments are passed to ideal via the following pattern: --{key}={value}. Where arguments are boolean, no value is required and their presence consistutes true.

See below for full list of configurable options:

| Key | Value | Default | About | | ------------ | ------ | ------- | --------------------------------------------------------------- | | --outputPath | Path | ./dist | A relative path to where you would like files to be written | | --release | N/A | false | Determine whether files are built for development or production | | --sourceMap | N/A | false | Output source maps to built assets | | --cssModules | N/A | false | Hash class names and build a json map file | | --watch | N/A | false | Watch files for changes | | --watchPath | N/A | null | Path to where source files are being watched | | --verbose | N/A | false | Output more info in the console | | --pathAlias | Path | ./src | Define a path alias for webpack | | --filePrefix | String | null | Prepend this value to built assets, useful for versioning |

Config File

The structure of the ideal.config.js file can be seen below. Each top level property key matches a particular build task, e.g build:css.

module.exports = {
   'build:css': {
      cssModules: true,
      watchPath: './src/**/*.scss',
      ...
   },
   'build:js': {
      watchPath: './src/**/*.ts,
      ...
   }
};

This is then picked up at runtime by ideal. Each set of properties match their CLI equivelants, in value and casing.

Webpack Specific

ideal allows you to manually specify a webpack.config.js file in the root directory of where ideal is being run from. If this file is found, these values will be used, if not a default config will be used instead.

Manifest

ideal creates an assets.json file in the output directory (./dist by default), that keeps a record of all assets built so far. Each subsequent run of ideal appends each file name as a property with the hashed or real file name as a value. Each build overides previous asset names or declares new ones that don't yet exist. This file is intended to be ephermeral, e.g when running a production build with --release, this file should not exist in the output path. Equally the assets.json file should not be commited to your repository. This ensures that the file is an accurate reflection of the built files for the currently provided source.

Development

Once you've cloned this repo and run yarn, then yarn start, you can make use of npm link to simulate how this package will work when installed globally. From there, you can run the following in a directory of your choice to run a build:

$ ideal build:js ./path/to/stuff --watch