timpla/README.md

<!-- STOP! Don't edit me. Look at local.gulpfile.js/README.md and build from there. -->

<div align="center">

<!-- Typedocs will have a copy of ./media in its own folder -->
<img src="media/timpla-logo.png" width="182" height="100" />

Your auntie's favourite asset bundler for [server-side] web frameworks. Provides an optimal web-development experience for TypeScript and/or ESNext.

Powered by gulp 4 & webpack 4.

[![Greenkeeper badge](https://badges.greenkeeper.io/igimanaloto/timpla.svg)](https://greenkeeper.io/)
[![Build Status](https://travis-ci.org/igimanaloto/timpla.svg?branch=master)](https://travis-ci.org/igimanaloto/timpla)
[![Coverage Status](https://coveralls.io/repos/github/igimanaloto/timpla/badge.svg)](https://coveralls.io/github/igimanaloto/timpla)
[![npm version](https://badge.fury.io/js/timpla.svg)](https://badge.fury.io/js/timpla)

</div>

- [Getting started](#getting-started)
  - [Installation](#installation)
  - [The Timpla-way of thinking](#the-timpla-way-of-thinking)
  - [Commands](#commands)
  - [Debugging](#debugging)
  - [Influence](#influence)
- [Configuring Timpla](#configuring-timpla)
  - [List of available options](#list-of-available-options)
  - [The timplaHelper object](#the-timplahelper-object)
  - [Specifying a config file on runtime](#specifying-a-config-file-on-runtime)
  - [Overriding babel & babel-loader options](#overriding-babel---babel-loader-options)
  - [Configuring Webpack](#configuring-webpack)
  - [Overriding tasks](#overriding-tasks)
  - [TypeScript](#typescript)
  - [Disabling TypeScript / TSLint](#disabling-typescript---tslint)
  - [ESLint](#eslint)
  - [Disabling ESLint](#disabling-eslint)
- [The three levels of reloading](#the-three-levels-of-reloading)
  - [BrowserSync injection and reloading](#browsersync-injection-and-reloading)
  - [Hot module reloading + React HMR](#hot-module-reloading---react-hmr)
    - [Dev-server reloading based on config file changes](#dev-server-reloading-based-on-config-file-changes)
- [Common setups](#common-setups)
  - [Using Timpla as a static html workflow](#using-timpla-as-a-static-html-workflow)
  - [Using Timpla with an existing site (Proxy option)](#using-timpla-with-an-existing-site--proxy-option-)
  - [Replacing the html task with Shopify Liquid templating](#replacing-the-html-task-with-shopify-liquid-templating)
- [Common Problems](#common-problems)
  - [I'm getting a different version of dependency X when I use Timpla!](#i-m-getting-a-different-version-of-dependency-x-when-i-use-timpla-)
  - [Timpla doesn't pick up changes to my eslintrc](#timpla-doesn-t-pick-up-changes-to-my-eslintrc)
  - [When I build, javascript files don't work!](#when-i-build--javascript-files-don-t-work-)
  - [process.cwd() isn't working as it's supposed to!](#processcwd---isn-t-working-as-it-s-supposed-to-)
  - [Tips for working with npm linked dependencies](#tips-for-working-with-npm-linked-dependencies)
- [CAQIAs (Commonly asked questions I ask)](#caqias--commonly-asked-questions-i-ask-)
- [Developing the plugin](#developing-the-plugin)
- [Releasing the plugin](#releasing-the-plugin)

## Getting started

Timpla aims is to provide you with an excellent web development experience. Timpla focuses on the truly defined parts in every build process: preparing javascript, css and media files for your websites. Three layers of reloading power Timpla: CSS-injection/reloading via BrowserSync (proxy or server), Webpack JS/TS Hot Module Reloading and full dev-server reloads based on core config changes.

Unlike a `boilerplate` or a `full-blown` development framework, the rational behind Timpla is that of guiding users with an undiscriminating base. You bring your own dependencies to enhance and/or extend the core Timpla build pipeline.

Timpla maintains its own side of the fence, while you focus on the more important aspects of your workflow, or better yet - getting straight into work!

You may wonder why bother with Timpla if Webpack does everything. Timpla by no means undermines what Webpack is already able to achieve! However, in our quest to find a sweet development environment, we've come to realise that forcing everything through Webpack yields painful load and reload times. Timpla's performance and tooling in a decently sized project is something we're proud of!

<!-- Typedocs will have a copy of ./media in its own folder -->
<img src="media/timpla-sample.jpg" />

### Installation

We recommend that you install Timpla as a whole first first, and removing bits that you do not need. See [Configuring Timpla](#configuring-timpla) for more info.

```sh
# Base install
npm i --save-dev timpla webpack @babel/core

# Run these too to get Timpla up and running after npx timpla init.
# The dependencies below are for extending Timpla to have both
# TypeScript and Javascript running in parallel.
# Each of the dependencies here are removeable, so we recommend
# installing the whole bunch first to see how everything works.
# Slim it down afterwards based on your requirements!
npm i --save-dev react react-dom react-hot-loader prettier @babel/preset-env @babel/polyfill @babel/preset-typescript @babel/preset-react eslint eslint-loader babel-eslint eslint-config-prettier eslint-plugin-react tslint-config-prettier typescript tslint tslint-react @types/react @types/react-dom webpack-bundle-analyzer hard-source-webpack-plugin fork-ts-checker-webpack-plugin speed-measure-webpack-plugin

# Initialise timpla
# Careful: outputs config files and a starter src directory:
#  babel.config.js
#  .eslintrc
#  tsconfig.json
#  tslint.json
#  .prettierrc
#  .timplaconfig.js
npx timpla init

# Start the dev-server
npx timpla

# Build all asset files
npx timpla build
```

### The Timpla-way of thinking

Timpla is a process-driven tool. Each `asset stream` holds a pre-defined and parallelised part in the Timpla build chain. The following assets are built in parallel:

- `Sass` files are compiled into css files, so you may load it as normal in your templates.
- `SVG` files are combined into single-svgs for use, either via direct insertion into your templates, or your javascript-driven loading.
- `Image` and `static` asset files are simply copied, but the processes are extendible, wherein you can tap into the build-stream and introduce your own pre-processing tasks.
- `Javascript and/or Typescript` files bundled using Webpack.
- Useful tooling such as file size reports, file-revving, bundle analysis and Webpack performance measurements are made available to further enhance your development process.

In every dev or production build, `prebuild` and `postbuild` hooks are available for you to enhance the Timpla process. Apart from the javascript task, you may replace how each asset-type is processed via Timpla's alternateable tasking system.

Timpla also allows you to register extra tasks via Gulp. These may be added to the pre or post parts of the build process.

Timpla nukes the `destination` folder for every dev or production start. This ensures that you treat the `src` directory as the one true source for raw source files.

### Commands

```sh
# Timpla starts the development server by default (npx timpla)
npx timpla [command]

[command]
init # inits timpla (copies initial src and config files to project root)
initConfig # recreates the .timplaconfig.js file in the project root
build # outputs build files
clean # cleans the dest directory
javascripts # builds js and ts files
rev # revs files and outputs a manifest file (designed for html/basic use-cases only)
sizeReport # shows a file sizes report
svg # combines svg files into one
stylesheets # transpiles sass/scss files to css
openAnalyzer # opens the bundle analyzer (run this after a build)
fonts # copies files from font src to dest
images # copies files from images src to dest
staticFiles # copies files from static src to dest
html # copies files from html src to dest
```

These will be available as `npx timpla [yourcustomtask]`.

You can also set up npm scripts to simplify the commands:

```json
# You package.json file
{
  "scripts": {
    "build": "timpla build",
    "start": "timpla",
    "tasks": "npx timpla --tasks"
  }
}
```

### Debugging

Enable verbose logs by running any timpla command with env DEBUG=timpla:

```sh
DEBUG=timpla timpla [command]
```

To view a breakdown of plugin / loader times, you may also enable it by setting MEASURE=1:

```sh
MEASURE=1 timpla [command]
```

This is done through `speed-measure-webpack-plugin`, so you'll need to have that installed in your project. ForkTS Checker breaks when this is run along-side it, so we have decided not to make it separate from the rest of the debug process. Follow the [issue here](https://github.com/stephencookdev/speed-measure-webpack-plugin/issues/56).

### Influence

Server-side frameworks like Django, Rails, Craft, Wordpress and Laravel come with templating engines that require access to static assets.

Timpla brings back the ol' 'just-output-built-files' approach to asset bundling.

This plugin provides a drop-in asset bundling system to complement your favourite server-side framework. It streamlines your build and development processes through the following features:

- Bundling JS/TS via Webpack
- On-screen ESLint and/or TSLint feedback
- Compiling sass and scss files
- Bundling svgs via SVGStore
- Copying static fonts, images and other files, with support for extending their workflows.
- Live-reloading via browsersync and webpack hmr (dev), with support for React Hot Module reloading

To be exact, Timpla uses the following technologies:

- Gulp
- Webpack
- BrowserSync
- Node-sass
- Babel
- SVGStore
- ESLint (dev-only)
- TypeScript
- TSLint (dev-only)

Timpla also provides TSLint and ESLint support for development-mode. Having errors on an overlay are helpful! On production builds, Timpla disables these to speed up compilation times. Please use an alternative process for production builds, if you wish to lint files.

Timpla started as a fork of [Blendid](https://github.com/vigetlabs/blendid), and continues to carry the torch for providing awesome server-side-driven dev experiences.

## Configuring Timpla

One of Timpla's aims is to be zero-configuration. By default, Timpla is set to run in HTML mode and displays an html page. Browsersync may be used to `mount` on top of your existing project.

The most basic Timpla configuration follows:

<!-- inject:timpla_config_basic:js -->
```javascript
// @ts-check

/**
 * The @type annotations are harmless, vscode might just make your life easier
 * by adding intellisense support whilst you type!
 */

const { configure } = require('timpla')

module.exports = configure({
  javascripts: {
    /** @type { import("timpla").ITimplaWebpackEntryHook } */
    entry: ({ resolve: r }) => ({
      'js-index': r('./js-index.jsx'),
      'ts-index': r('./ts-index.tsx'),
      'ts-error': r('./ts-error.ts'),
    }),

    /** @type { import("timpla").ITimplaCustomizeWebpackConfig } */
    customizeWebpackConfig(w) {
      // The following helpers are available to aid you in extending the webpack config.
      const {
        projectDestPath,
        projectSrcPath,
        timplaConfig,
        timplaProcess,
        webpack,
        webpackConfig,
        webpackMerge,
      } = w
      return w.webpackConfig
    },
  },

  // To get intellisense for more complex configs, follow the jsdoc example below:
  // html: {
  //   /** @type { import("timpla").ITimplaHofTask } */
  //   alternate: p => {
  //     p.timplaProcess
  //   },
  // },

  //  additionalTasks: {
  //    /** @param p { import("timpla").ITimplaHelper } */
  //    initialize: p => {},
  //    development: {
  //      /** @type { import("timpla").ITimplaHofTask } */
  //      prebuild(tp) {},
  //    },
  //  },
})

```
<!-- endinject -->

Tasks such as html, static and images copy files from the src to the dest folder. Use the `alternate` option to define processing logic. To keep Timpla light, no preprocessing happens for image and other static files. It is left to you to add your preferred workflows. (see alternate configs for reach of the asset tasks below)

Full configuration is available through `.timplaconfig.js`. You'll get a copy in your project's root folder after running `npx timpla init`.

Timpla exports a helper function called `configure`. Use this to create a timplaconfig object in your `.timplaconfig.js`. As an added benefit, your IDE's intellisense should suggest what options are available!

### List of available options

[Full TS documentation](https://igimanaloto.github.io/timpla/interfaces/_lib_timplainterfaces_.ifulltimplaconfig.html) of the timpla config object is available for viewing. An excerpt of the full timpla config follows:

<!-- inject:timpla_config:ts -->
```typescript

export interface IFullTimplaConfig {
  /** The base folder to include for compilation. Defaults to `./src`. */
  src: string
  /** The base folder to output bundled files to. Defaults to `./dest`. */
  dest: string
  /*
   * Instructs timpla on how to run the staticFiles task.
   * Set to `false` to disable the task.
   */
  staticFiles:
    | false
    | {
        /** The folder to include for compilation. Defaults to `static`. */
        src: string
        /** The folder to output bundled files to. Defaults to `./`. */
        dest: string
        /** Options to pass to the gulp src task. This setting is ignored when an alternate task is provided. */
        srcOptions: SrcOptions
        /** Options to pass to the gulp dest task. This setting is ignored when an alternate task is provided. */
        destOptions: DestOptions
        /** A custom task to override the default with. */
        alternate?: ITimplaHofTask
      }
  /**
   * Instructs timpla on how to run the clean task.
   * Set to `false` to disable the task.
   */
  clean:
    | false
    | {
        /**
         * Extra files and folders to `clean` before Timpla runs the dev-server or full-build.
         * `Please take great care when specifying your own patterns`
         * Accepts an array of globs. Defaults to the project `dest` directory.
         */
        patterns?: string | ReadonlyArray<string>
        /** Options to pass to the del function. */
        delOptions: Options
      }

  /** Watch task options */
  watch: {
    /**
     * Gulp watch options.
     * Accepts gulp watch options for all tasks,
     * or a keyed-list of watch-options to apply to tasks individually.
     * - E.g. gulpWatch.svg = {} sets specific configs for the svg task.
     */
    gulpWatch: {
      [name: string]: any
    }
  }

  /**
   * Instructs timpla on how to run the stylesheets task.
   * Set to `false` to disable the task.
   */
  stylesheets:
    | false
    | {
        /** The folder to include for compilation. Defaults to `stylesheets`. */
        src: string
        /** The folder to output bundled files to. Defaults to `stylesheets`. */
        dest: string
        /** Options to pass to the gulp src task. This setting is ignored when an alternate task is provided. */
        srcOptions: SrcOptions
        /** Options to pass to the gulp dest task. This setting is ignored when an alternate task is provided. */
        destOptions: DestOptions
        /** [Cssnano](https://www.github.com/cssnano/cssnano) options */
        cssnanoOptions: CssNanoOptions
        /** [Autoprefixer](https://github.com/postcss/autoprefixer#options) options */
        autoprefixerOptions: autoprefixer.Options
        /** [PostCSS](https://github.com/postcss/postcss#options) options */
        postcssOptions: postcss.ProcessOptions
        /** [Gulp/Node sass](https://www.npmjs.com/package/gulp-sass) options */
        sassOptions: INodeSassOptions
        /** A list of extensions for BrowserSync to watch. Defaults to `['sass', 'scss', 'css']`. */
        extensions: string[]
        /** Development-specific stylesheets options */
        development: {
          /** Defaults to `true`. */
          sourceMap: boolean
        }
        /** Production-specific stylesheets options */
        production: {
          /** Defaults to `false`. */
          sourceMap: boolean
        }
        /** A custom task to override the default with. */
        alternate?: ITimplaHofTask
      }
  /**
   * Instructs timpla on how to run the fonts task.
   * Set to `false` to disable the task.
   */
  fonts:
    | false
    | {
        /** The folder to include for compilation. Defaults to `fonts`. */
        src: string
        /** The folder to output bundled files to. Defaults to `fonts`. */
        dest: string
        /** Options to pass to the gulp src task. This setting is ignored when an alternate task is provided. */
        srcOptions: SrcOptions
        /** Options to pass to the gulp dest task. This setting is ignored when an alternate task is provided. */
        destOptions: DestOptions
        /** A list of extensions for BrowserSync to watch. Defaults to `['woff2', 'woff', 'eot', 'ttf', 'svg']`. */
        extensions: string[]
        /** A custom task to override the default with. */
        alternate?: ITimplaHofTask
      }
  /**
   * Instructs timpla on how to run the images task.
   * Set to `false` to disable the task.
   */
  images:
    | false
    | {
        /** The folder to include for compilation. Defaults to `images`. */
        src: string
        /** The folder to output bundled files to. Defaults to `images`. */
        dest: string
        /** Options to pass to the gulp src task. This setting is ignored when an alternate task is provided. */
        srcOptions: SrcOptions
        /** Options to pass to the gulp dest task. This setting is ignored when an alternate task is provided. */
        destOptions: DestOptions
        /** A list of extensions for BrowserSync to watch. Defaults to `['jpg', 'png', 'svg', 'gif']`. */
        extensions: string[]
        /** A custom task to override the default with. */
        alternate?: ITimplaHofTask
      }
  /**
   * Instructs timpla on how to run the svg task.
   * Set to `false` to disable the task.
   */
  svg:
    | false
    | {
        /** Options for the gulp-svg plugin. */
        svgstore: IGulpSvgStore
        /** The output filename for the concatanted svg file. Defaults to `icons.svg`. */
        outputName: string
        /** The folder to include for compilation. Defaults to `svg`. */
        src: string
        /** The folder to output bundled files to. Defaults to `images`. */
        dest: string
        /** Options to pass to the gulp src task. This setting is ignored when an alternate task is provided. */
        srcOptions: SrcOptions
        /** Options to pass to the gulp dest task. This setting is ignored when an alternate task is provided. */
        destOptions: DestOptions
        /** A custom task to override the default with. */
        alternate?: ITimplaHofTask
      }
  /**
   * Instructs timpla on how to run the html task.
   * Set to `false` to disable the task.
   */
  html:
    | false
    | {
        /** The folder to include for compilation. Defaults to `html`. */
        src: string
        /** The folder to output bundled files to. Defaults to ``. */
        dest: string
        /** Options to pass to the gulp src task. This setting is ignored when an alternate task is provided. */
        srcOptions: SrcOptions
        /** Options to pass to the gulp dest task. This setting is ignored when an alternate task is provided. */
        destOptions: DestOptions
        /** A custom task to override the default with. */
        alternate?: ITimplaHofTask
      }
  /**
   * Instructs timpla on how to run the javascripts task.
   */
  javascripts: {
    /** The folder to include for compilation. Defaults to `javascripts`. */
    src: string
    /** The folder to output bundled files to. Defaults to `javascripts`. */
    dest: string
    /** A list of extensions for BrowserSync to watch and Webpack to load. Defaults to `['js', 'jsx', 'ts', 'tsx']`. */
    extensions: string[]
    /**
     * The webpack entry config.
     * Accepts a Timpla-flavoured entry function or a webpack entry object.
     * Webpack is configured to use the projectRoot as the cwd.
     * Files you point in the entry config need to have the relative path to the javascripts folder.
     * Use the `resolve` helper to resolve files to the js src folder.
     */
    entry: ITimplaWebpackEntry
    /**
     * Instructs webpack the base path for all the assets within your application.
     * Defaults to the `javascripts.dest` path. e.g. `/javascripts`
     */
    publicPath?: string
    /**
     * Options for the babelLoader. Accepts babel-loader specific as well as Babel options.
     * For more advanced use-cases, e.g. manually specifying the babel config file to use.
     * Defaults to
     * - `cacheDirectory: true`
     * - `cacheCompression: false`
     * - `root: your project root`
     */
    babelLoaderOptions: IBabelLoaderOptions
    /**
     * Accepts [webpackBundleAnalyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) options.
     * Set to `false` to disable webpackBundleAnalyzer.
     * Defaults to
     * - `statsFilename: timpla-webpack-stats.json`
     * - `openAnalyzer: true if Timpla hasn't fully reloaded.`
     */
    webpackBundleAnalyzerOptions: false | BundleAnalyzerPlugin.Options
    /**
     * A customisation function that allows modifying the generated
     * webpack config before it is passed to webpack.
     */
    customizeWebpackConfig: ITimplaCustomizeWebpackConfig

    /** Instructs timpla on how Webpack should run in dev-mode. */
    development: {
      /**
       * The webpack devtool to use.
       * Defaults to `cheap-module-eval-source-map`.
       */
      devtool: webpack.Options.Devtool
      /**
       * Accepts [Webpack Hot Middleware](https://github.com/webpack-contrib/webpack-hot-middleware) options.
       * Set to `false` to disable [hot module reloading](https://webpack.js.org/concepts/hot-module-replacement/).
       * Defaults to
       * - `reload: true`
       * - `quiet: true`
       */
      webpackHotMiddlewareOptions: IWebpackHotMiddlewareOptions | false
      /**
       * In dev-mode, Timpla supports ESLint via the ESLint loader.
       * By default, Timpla requires the eslint package to be installed.
       * - `npm i --save-dev eslint`
       * - Set to `false` to disable ESLint.
       */
      eslint: {
        /*
         * Accepts [eslint-loader](https://github.com/webpack-contrib/eslint-loader) & [eslint](http://eslint.org/docs/developer-guide/nodejs-api#cliengine) options.
         */
        esLintLoaderOptions: IESLintLoaderOptions
      }
      /**
       * In dev-mode, Timpla uses Fork TS Checker, a webpack plugin that runs typescript export type checker on a separate process.
       * By default, Timpla requires dependent packages to be installed.
       * - `npm i --save-dev typescript tslint fork-ts-checker-webpack-plugin`
       * - Set to `false` to disable the plugin, and TSLint support.
       */
      tslint:
        | {
            /** Accepts [Fork TS Checker](https://github.com/Realytics/fork-ts-checker-webpack-plugin) options. */
            forkTsCheckerOptions: IForkTsCheckerOptions
          }
        | false
    }

    /**
     * Instructs timpla on how to run Webpack in production.
     */
    production: {
      /**
       * The webpack devtool to use.
       * Defaults to `source-map`.
       */
      devtool: webpack.Options.Devtool
      /**
       * Timpla uses Hard Source to improve production build times.
       * Set to `false` to disable the plugin.
       * Accepts [hard-source-webpack-plugin](https://github.com/mzgoddard/hard-source-webpack-plugin) options.
       */
      hardSourceOptions: false | IHardSourceWebpackPluginOptions
      /**
       * [Terser Webpack Plugin](https://github.com/webpack-contrib/terser-webpack-plugin) options.
       * Timpla uses Terser to uglify the bundled JS files.
       * UglifyJS2 is outdated, and Terser is its successor.
       */
      terserConfig: Partial<{}>
    }
  }

  /**
   * Configures the BrowserSync task.
   * Accepts [browser-sync](https://browsersync.io/docs/options) options.
   *
   * May also be used to individually `disable` the default
   * middleware added to proxy and server modes via middlewareConfig:
   * - webpackDevMiddleware - disableDev
   * - webpackHotMiddleware - disableHot
   * - historyApiFallback - disableSpa
   *
   * Set proxy/server.middleware to `false` to disable middleware.
   */
  browserSync: ITimplaBrowserSyncOptions

  /** Instructs Timpla on after-build tasks. */
  production: {
    /**
     * Opens a specified target in an app after all the core-tasks run.
     * Uses the opn package to achieve this.
     * Defaults to `false`.
     */
    open: false | IOpenOptions
    /**
     * Enables file-reving (hashed filenames).
     * Timpla revs your files and generates a json manifest file.
     * You'll need to write your own mapper to pick up the filenames from the rev manifest file.
     * Defaults to `false`.
     */
    rev: boolean
  }

  /** Instructs Timpla on post-dev-launch tasks. */
  development: {
    /**
     * Opens a specified target in an app after all the core-tasks run.
     * Uses the opn package to achieve this.
     * Defaults to `false`.
     */
    open: false | IOpenOptions
    /**
     * Extra files and folders for Timpla to watch.
     * When these change, Timpla reloads the dev-server.
     * Set to `false` to disable this option.
     * Defaults to `true`.
     */
    timplaWatch: boolean | string[]
  }

  /** Instructs Timpla on additional tasks */
  additionalTasks: {
    /** An init function that runs before all the other Timpla. */
    initialize?: (timplaHelper: ITimplaHelper) => any
    /** Instructs Timpla to add extra `development tasks`. */
    development: {
      /** Adds an extra development `prebuild task`. Accepts a `higher-order-function`, i.e. returns a Gulp/Undertaker TaskFunction. */
      prebuild?: ITimplaHofTask
      /** Adds an extra development `postbuild task`. Accepts a `higher-order-function`, i.e. returns a Gulp/Undertaker TaskFunction. */
      postbuild?: ITimplaHofTask
    }
    /** Instructs Timpla to add extra `production tasks`. */
    production: {
      /** Adds an extra production `prebuild task`. Accepts a `higher-order-function`, i.e. returns a Gulp/Undertaker TaskFunction. */
      prebuild?: ITimplaHofTask
      /** Adds an extra production `postbuild task`. Accepts a `higher-order-function`, i.e. returns a Gulp/Undertaker TaskFunction. */
      postbuild?: ITimplaHofTask
    }
  }
}

/** The partialised Timpla Config so users' may opt in to only customise what they wish to. */
export type ITimplaConfig = IRecursivePartial<IFullTimplaConfig>

```
<!-- endinject -->

### The timplaHelper object

The following variables are available from the timplaHelper

```javascript
const timplaHelper = {
  browserSync, // Access the browserSync instance.
  gulp, // A gulp instance that can be used to register new tasks.
  projectDestPath, // Resolves a list of strings to the project's dest path.
  projectSrcPath, // Resolves a list of strings to the project's src path.
  timplaConfig, // The full timplaConfig
  timplaProcess, // Provides useful constants such as isDevelopment, isProduction and INIT_CWD (your project's resolved base path).
}
```

### Specifying a config file on runtime

To specify a timpla config on runtime, you may set the TIMPLA_CONFIG_FILE env like so:

`TIMPLA_CONFIG_PATH='./relative/path/to/file' npx timpla [command]`

### Overriding babel & babel-loader options

You may use javascripts.babelLoaderOptions to fully control how the webpack babel-loader works.

Babel config resolution is set to default, so babel.config.js and babelrc files are picked up by Timpla. We recommend using babel.config.js as opposed to a babelrc so that npm linked modules are also picked up by babel-loader, via Babel's root config resolution mechanism.

Timpla copies the following babel config file to your project folder. (babel.config.js) and pre-configures your .timplaconfig.js to pick this up.

<!-- inject:babel:js -->
```javascript
const debug = process.env.DEBUG === 'timpla'
const isProduction = process.env.NODE_ENV === 'production'

module.exports = {
  presets: [
    [
      '@babel/preset-env',
      {
        // usage automatically injects @babel/polyfill, so older browsers may still work
        // see https://babeljs.io/docs/en/babel-polyfill
        // We're only loading this for production builds so development compilation times are faster!
        ...(isProduction && { useBuiltIns: 'usage' }),
        debug,
      },
    ],
    '@babel/preset-typescript',
    '@babel/preset-react',
  ],
  plugins: ['react-hot-loader/babel'],
}

```
<!-- endinject -->

### Configuring Webpack

Webpack by default uses the following plugins (module.rules):

```sh
# HardSourceWebpackPlugin - disabled for now, as caching may break babel-loader 7.2 builds.
TerserPlugin # uglifies/minifies code
SpeedMeasurePlugin # Shows a useful breakdown of Webpack compilation speed. Runs when DEBUG=timpla is set.
ForkTsCheckerWebpackPlugin # creates a forked (separated) TSLint server to run alongside Timpla
BundleAnalyzerPlugin # provides a visual report of js bundle sizes
```

Each of these plugins are configurable/can be disabled. For example, javascripts.tslint.forkTsCheckerOptions accepts ForkTsCheckerWebpackPlugin configuration options.

In certain scenarios, Timpla lazy-loads plugins. This gives you the flexibility to `remove` packages that you don't need :). For example, setting javascripts.tslint to false disables tslint and loading the module itself. As a result, you may remove tslint and ForkTsCheckerWebpackPlugin from your dependencies.

Webpack also uses the following loaders:

```
babel-loader (ESNext and TypeScript support)
eslint-loader (dev-only)
```

You have access to the full webpack configuration before it gets fed to Webpack itself. This way, you can add extra loaders you wish to use. Please use the javascripts.customizeWebpackConfig rule in .timplaconfig.js. It accepts a function that returns a configuration object:

```javascript
// .timplaconfig.js
{
  // ... the rest of your config file
  javascripts: {
    customizeWebpackConfig({
      webpackConfig,
      timplaConfig,
      timplaProcess,
      webpack,
      projectDestPath,
      projectSrcPath,
      webpackMerge
    }) => {
      const modifiedConfig = { ...webpackConfig }
      // You can modify the config to how you want it

      // check if it's prod or development
      if (timplaProcess.isProduction) {
        // do this;
      }
      if (timplaProcess.isDevelopment) {
        // do this
      }

      // or even modify rules & plugins...
      modifiedConfig.plugins = modifiedConfig.plugins.filter(yourFilterFunction)
      modifiedConfig.module.rules.push(yourOwnRule)

      // or with the webpack merge plugin, you can even do a webpackMerge(webpackConfig, require('./yourOverrides'))

      return modifiedConfig
    }
  }
}
```

### Overriding tasks

You may overwrite any listed tasks with an alternate option. Please provide a higher order function (a function returning a function) that accepts a timplaHelper object. You may use these to help write the tasks. The higher order function should signal gulp completion: either through a manual callback call or by returning a gulp stream. If in doubt, always return an Undertaker TaskFunction!

A contrived example follows.

```javascript
{
  // ... the rest of your timpla config
  stylesheets: {
    // ... the rest of your stylesheets config
    alternate({
      browserSync,
      gulp,
      projectDestPath,
      projectSrcPath,
      timplaConfig,
      timplaProcess,
    }){
      const stylesheetsConfig = timplaConfig.stylesheets // access the stylesheets config
      const paths = {
        src: projectSrcPath(stylesheetsConfig.src, '**/*.{' + stylesheetsConfig.extensions + '}'),
        dest: projectDestPath(stylesheetsConfig.dest),
      }

      // We must return a higher order function
      return (cb) => {
        // if gulp is not being used, cb can be used to call signal completion
        // dosomethingElse();
        // cb()

        // We can also return a gulp stream instead
        return gulp
          .src(paths.src) // finds [your-project]/stylesheets/something.txt
          .pipe(yourOwnSassProcesser())
          .pipe(gulp.dest(paths.dest)) // transfers the file to [your-project]/stylesheets/somethingelse.txt
          .pipe(browserSync.stream()) // streams changes to browserSync
      }
    }
  }
}
```

### TypeScript

By default TypeScript and TSLint are enabled. TypeScript functionality is provided through babel-loader and @babel/preset-typescript. TSLint is enabled by default for development mode.

Timpla uses babel-loader with @babel/preset-typescript and [Fork TS Checker Webpack Plugin](https://github.com/Realytics/fork-ts-checker-webpack-plugin) to process TypeScript files. To improve compilation times, Timpla utilises the Fork TS Checker Webpack Plugin to create a separate linting process for TypeScript. Any linting errors won't block the webpack compilation process but will display either in the console or as an overlay on the web page.

For production builds, TSLint is disabled. We've found that it is better to run TSLint as a separate production process.

### Disabling TypeScript / TSLint

If you followed the installation instructions above, please uninstall the following packages: `fork-ts-checker-webpack-plugin`, `tslint`, and `typescript`. Remove @babel/preset-typescript from babel.config.js. Finally, set javascripts.development.tslint to false.

### ESLint

ESLint is enabled for dev-mode. Timpla requires you to have an eslintrc file in your project directory, as well the eslint-loader package installed. Eslintrc resolution is left to the eslint-loader plugin, which means that it should pick up child-dir eslintrc files.

### Disabling ESLint

Set javascripts.development.eslint to false if you don't require it. As eslint-loader is loaded conditionally, you may uninstall it if you don't require eslint.

## The three levels of reloading

### BrowserSync injection and reloading

Timpla uses BrowserSync to inject stylesheets and notify the browser of full-reloads when files change. Timpla pre-configures the watched files for you, but you may also extend it through the `files: [globs]` config.

```javascript
module.exports = {
  browserSync: {
    files: ['when_this_changes_reload_the_page/**/*'],
  },
}
```

When writing your own tasks, Timpla Helper passes the browserSync instance so you may stream(inject) your changes on the fly!

### Hot module reloading + React HMR

Any files you mark as hot won't cause the browser to reload. This is useful when you need to keep the browser in its current state.

Hot module reloading is enabled by default. Setting `javascripts.development.webpackHotMiddlewareOptions` to `false` disables it.

To support react hot module reloading, please install and add `react-hot-loader/babel` to your `babel.config.js`'s plugins. This should be fine even for production builds, as react-hot-loader adds minimal footprint to your code.

#### Dev-server reloading based on config file changes

Timpla fully reloads the dev-server whenever your config files such as babel config, tsconfig, tslint and eslint files change. This saves you the hassle of having to restart just to test configuration settings!

You may also extend the watched files/folders by adding them to .timplaconfig.js > development.timplaWatch. Timpla iterates through these files and sets up reload watchers. You may provide resolved or relative paths.

Setting `development.timplaWatch` to `false` disables the reload server.

## Common setups

### Using Timpla as a static html workflow

Out of the box, Timpla is configured to serve an html page.

### Using Timpla with an existing site (Proxy option)

More often than never, server-side frameworks run your site on localhost (or a locally configured server). Timpla can mount on your site through BrowserSync's proxy option.

To use timpla with an existing site, you may follow the sample browsersync config below. You run your server-side framework and Timpla in a separate process. Use the browserSync option in .timplaconfig.js to set BrowserSync options - it accepts a configuration object. An example of getting it to work with Django/Rails/Laravel follows:

```javascript
// .timplaconfig.js
const { configure } = require('timpla')
const path = require('path')

// You would most probably want to react to template changes, you may set extra folders here (relative)
const extraWatchFiles = ['templates/**/*']

// The local instance of your site that Timpla will proxy to
const proxyTarget = 'http://127.0.0.1:7025'

// Access the site via localhost:localhostPort
const localhostPort = 5605

// If you are using nginx/htaccess to point a host to a local port
// This is useful if CORS headers are set on your local site resources (CDN)
const host = 'http://local-new.grabone.co.nz'

module.exports = configure({
  browserSync: {
    proxyTarget,
    files: extraWatchFiles,
    port: localhostPort,
    cors: true,
    proxy: {
      target: proxyTarget,
      proxyReq: [
        // Additional request headers may be added here
        function(proxyReq) {
          proxyReq.setHeader('host', host.replace(/^https?:\/\//i, ''))
          // grabone authentication requires proper host header to be set
          proxyReq.setHeader('Access-Control-Allow-Origin', '*')
        },
      ],
    },
    files: files.map(fileGlob => path.join(process.env.PWD, fileGlob)),
    host,
    // Prevent browsersync from automatically opening the site (can get annoying pretty quickly)
    open: false,
    online: false,
  },
  // ... the rest of your config
})
```

### Replacing the html task with Shopify Liquid templating

The following example shows how to get Shopify liquid templating support. We'll override the html task to run the html files through liquidr via gulp-liquidr.

The same approach can be made to pull in gulp-pug, gulp-haml, gulp-slim and gulp-jinja!

```javascript
// make sure to run npm i --save gulp-liquidr first
const { configure } = require('timpla')
const liquidr = require('gulp-liquidr')
const changed = require('gulp-changed')

module.exports = configure({
  // ... the rest of your file
  html: {
    src: 'html',
    dest: './',
    // An alternative task may be defined to replace the default
    alternate({ gulp, env, timplaConfig, browserSync, projectSrcPath, projectDestPath }) {
      const htmlConfig = timplaConfig.html
      const paths = {
        src: [projectSrcPath(htmlConfig.src, '**/*.html')],
        dest: projectDestPath(htmlConfig.dest),
      }

      return () =>
        gulp
          .src(paths.src)
          .pipe(changed(paths.dest))
          .pipe(
            liquidr({
              root: [projectSrcPath(htmlConfig.src)],
              data: {
                accessMeInYourTemplate: 'ishouldwork',
              },
              // other config available from https://www.npmjs.com/package/gulp-liquidr
            })
          )
          .pipe(gulp.dest(paths.dest))
          .pipe(browserSync.stream())
    },
  },
})
```

## Common Problems

### I'm getting a different version of dependency X when I use Timpla!

Run `npm i --save/--save-dev [your-package`] to ensure that Webpack picks up your preferred package version.

### Timpla doesn't pick up changes to my eslintrc

This is a known [issue](https://github.com/webpack-contrib/eslint-loader/issues/214) with eslint-loader. Ensure that cache is turned off whilst a patch is being worked on. Alternatively, you may specify your own eslint caching strategy via `cacheIdentifer`.

### When I build, javascript files don't work!

We have encountered this happening whenever you switch the `production.rev` setting. Please clear `./node_modules/cache` to force-clear all caches and try again!

### process.cwd() isn't working as it's supposed to!

Gulp / Timpla sets the process.env.INIT_CWD to the current projectRoot whereas process.cwd() points to the node_modules/timpla folder. Please ensure that you use INIT_CWD instead to resolve to projectPaths.

### Tips for working with npm linked dependencies

Ensure that you are using a babel.config.js. This will allow babel-loader to process the linked module files (TypeScript and ESNext).

1. npm link yourmodule
1. set up a module.resolve rule for webpack e.g. yourmodule\$: path.resolve(\_\_dirname, 'node_modules/yourmodule/src/index.ts')

## CAQIAs (Commonly asked questions I ask)

<details>
  <summary>Is this workflow right for me?</summary>
  <p>
    If you are working on a server-side web framework like Django, Rails, Laravel, Shopify, Wordpress, Drupal or Craft - then yes! Timpla works along-side your engine's web templating system by dealing only with building your site assets. Timpla provides live-reloading and a sweet build process - so you can worry less about setup and more about writing code!
  </p>
  <p>
    If you are working on a single page application or a client-side library/framework (e.g. Vue, React and Angular), it's best to go for a client-side boilerplate. The returns will diminish with no-backbone apps.
  </p>
</details>
<details>
  <summary>Gulp? Task runners are no longer required!</summary>
  <p>Gulp still solves the issue of running tasks. Instead of polluting your npm run scripts or ad-hoc writing your build scripts, Gulp provides an easy-to-pick-up DSL for writing tasks.</p>
  <p>Although gulp plugins are long past their debut, most of them are still relevant to our tasking needs.</p>
  <p>Gulp is useful as it opens up streams to BrowserSync and Webpack.</p>
</details>
<details>
  <summary>Gem/plugin/package X provides webpack middleware...</summary>
  <p>
    Yes, there are packages, gems or composer plugins that allow injecting webpack via middleware into your asset pipeline.
  </p>
  <p>
    These tools are great, but often do we care less the older project dev environments get. By delegating the `core` to Timpla, we hope that more focus is put on extending, rather than maintaining!
  </p>
  <p>
    Also, we often get into the framework-exclusivity. Think of Timpla as a consistent tool to bring over to projects.
  </p>
</details>
<details>
  <summary>How different is this from Blendid?</summary>
  <p>
    After a fork to upgrade dependencies, it was decided to branch out to provide an updated and extensive configuration framework.
  </p>
</details>
<details>
  <summary>Does it optimise images or fonts?</summary>
  <p>Timpla only copies images and fonts to their destination folders. It is recommended that you optimise the images separately, so as not to overload the build process. If you really want to, use the alternate() config.</p>
</details>
<details>
  <summary>Why not inject stylesheets?</summary>
  <p>Critical-css, lesser requests through service workers / caching and css-in-html have benefits too :)</p>
</details>
<details>
  <summary>Is this production ready?</summary>
  <p>We use Timpla for [Grabone](https://grabone.co.nz). We invite you to share ideas, and raise issues if you find any! The added benefit of reusing existing gulp tasks is that they are tested independently, dropping the need to duplicate tests!</p>
</details>

## Developing the plugin

Files are written in TypeScript, so program to your heart's content. Dev plugins are loaded only in your environment, so they don't get shipped as part of the main package!

```sh
cd [timpla folder]
npm install
npm run lib:start # starts the tsc watcher, compiling gulpfile.ts on the go.

# In a separate terminal
cd [your project]
npm link timpla
```

When npm-linked, make sure you execute your commands using `timpla`.

## Releasing the plugin

1. Make changes
1. pr > Commit those changes to a separate PR
1. pr > Make sure Travis turns green
1. master > Merge PR
1. master > Bump version in package.json
1. master > npm run lib:changelog (needs to be installed first)
1. master > npm run lib:docs (builds the ts-docs and readme files)
1. master > Commit package.json and docs, README.md and CHANGELOG.md files
1. master > Tag
1. master > Push
1. npm publish