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.

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!

Installation

We recommend that you install Timpla as a whole first first, and removing bits that you do not need. See Configuring Timpla for more info.

npm i --save-dev timpla webpack @babel/core npm i --save @babel/polyfill @babel/preset-env @babel/preset-react @hot-loader/react-dom babel-eslint eslint eslint-config-prettier eslint-loader eslint-plugin-react hard-source-webpack-plugin prettier react react-dom react-hot-loader speed-measure-webpack-plugin webpack-bundle-analyzer node-sass npm i --save @babel/preset-typescript @types/react @types/react-dom typescript tslint tslint-config-prettier tslint-react fork-ts-checker-webpack-plugin npx timpla init npx timpla initJS npx timpla 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.

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.

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.

and 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.

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

npx timpla [ command ] [ command ] init initConfig build clean javascripts rev sizeReport svg stylesheets openAnalyzer fonts images staticFiles html

These will be available as npx timpla [yourcustomtask] .

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

# 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:

DEBUG=timpla timpla [ command ]

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

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.

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, 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:

const { configure } = require ( ' timpla ' ) module . exports = configure ( { javascripts : { entry : ( { resolve : r } ) => ( { ' js-index ' : r ( ' ./js-index.jsx ' ) , ' ts-index ' : r ( ' ./ts-index.tsx ' ) , ' ts-error ' : r ( ' ./ts-error.ts ' ) , } ) , customizeWebpackConfig ( w ) { const { projectDestPath , projectSrcPath , timplaConfig , timplaProcess , webpack , webpackConfig , webpackMerge , } = w return w . webpackConfig } , } , } )

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 of the timpla config object is available for viewing. An excerpt of the full timpla config follows:

export interface IFullTimplaConfig { | false | { src : string dest : string srcOptions : SrcOptions destOptions : DestOptions alternate ? : ITimplaHofTask } | false | { patterns ? : string | ReadonlyArray < string > delOptions ? : Options } | false | { src : string dest : string srcOptions : SrcOptions destOptions : DestOptions cssnanoOptions : CssNanoOptions autoprefixerOptions : autoprefixer . Options postcssOptions : postcss . ProcessOptions sassOptions : INodeSassOptions extensions : string [ ] development : { sourceMap : boolean } production : { sourceMap : boolean } alternate ? : ITimplaHofTask } | false | { src : string dest : string srcOptions : SrcOptions destOptions : DestOptions extensions : string [ ] alternate ? : ITimplaHofTask } | false | { src : string dest : string srcOptions : SrcOptions destOptions : DestOptions extensions : string [ ] alternate ? : ITimplaHofTask } | false | { svgstore : IGulpSvgStore outputName : string src : string dest : string srcOptions : SrcOptions destOptions : DestOptions alternate ? : ITimplaHofTask } | false | { src : string dest : string srcOptions : SrcOptions destOptions : DestOptions alternate ? : ITimplaHofTask } } export type ITimplaConfig = IRecursivePartial < IFullTimplaConfig >

The timplaHelper object

The following variables are available from the timplaHelper

const timplaHelper = { browserSync , gulp , projectDestPath , projectSrcPath , timplaConfig , timplaProcess , }

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.

const debug = process . env . DEBUG === ' timpla ' const isProduction = process . env . NODE_ENV === ' production ' module . exports = { presets : [ [ ' @babel/preset-env ' , { ... ( isProduction && { useBuiltIns : ' usage ' } ) , debug , } , ] , ' @babel/preset-typescript ' , ' @babel/preset-react ' , ] , plugins : [ ' react-hot-loader/babel ' ] , }

Configuring Webpack

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

TerserPlugin SpeedMeasurePlugin ForkTsCheckerWebpackPlugin BundleAnalyzerPlugin

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:

{ javascripts : { customizeWebpackConfig ( { webpackConfig , timplaConfig , timplaProcess , webpack , projectDestPath , projectSrcPath , webpackMerge } ) => { const modifiedConfig = { ... webpackConfig } if ( timplaProcess . isProduction ) { } if ( timplaProcess . isDevelopment ) { } modifiedConfig . plugins = modifiedConfig . plugins . filter ( yourFilterFunction ) modifiedConfig . module . rules . push ( yourOwnRule ) 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.

{ stylesheets : { alternate ( { browserSync , gulp , projectDestPath , projectSrcPath , timplaConfig , timplaProcess , } ) { const stylesheetsConfig = timplaConfig . stylesheets const paths = { src : projectSrcPath ( stylesheetsConfig . src , ' **/*.{ ' + stylesheetsConfig . extensions + ' } ' ) , dest : projectDestPath ( stylesheetsConfig . dest ) , } return ( cb ) => { return gulp . src ( paths . src ) . pipe ( yourOwnSassProcesser ( ) ) . pipe ( gulp . dest ( paths . dest ) ) . pipe ( browserSync . stream ( ) ) } } } }

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 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

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.useTypeScript to false.

Disabling TSLint

Please set development.tslint to false. You may also opt to uninstall tslint and fork-ts-checker-webpack-plugin as these won't be loaded by Timpla anymore.

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 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.

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!

Configuring BrowserSync middleware

Timpla uses webpack-hot-middleware , webpack-dev-middleware and connect-history-api-fallback by default. Each of these accept config objects, via development.middlewareConfig . You may disable any of them by passing false to their config key, e.g. development.middlewareConfig.webpackHotMiddleware: false . If you wish to disable everything, then set middlewareConfig to false .

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 development.webpackHotMiddlewareClient or development.middlewareConfig.webpackHotMiddleware 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:

const { configure } = require ( ' timpla ' ) const path = require ( ' path ' ) const extraWatchFiles = [ ' templates/**/* ' ] const proxyTarget = ' http://127.0.0.1:7025 ' const localhostPort = 5605 const host = ' http://local-new.grabone.co.nz ' module . exports = configure ( { browserSync : { proxyTarget , files : extraWatchFiles , port : localhostPort , cors : true , proxy : { target : proxyTarget , proxyReq : [ function ( proxyReq ) { proxyReq . setHeader ( ' host ' , host . replace ( / ^ https ? : \/ \/ / i , ' ' ) ) proxyReq . setHeader ( ' Access-Control-Allow-Origin ' , ' * ' ) } , ] , } , files : files . map ( fileGlob => path . join ( process . env . PWD , fileGlob ) ) , host , open : false , online : false , } , } )

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!

const { configure } = require ( ' timpla ' ) const liquidr = require ( ' gulp-liquidr ' ) const changed = require ( ' gulp-changed ' ) module . exports = configure ( { html : { src : ' html ' , dest : ' ./ ' , 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 ' , } , } ) ) . 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 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).

npm link yourmodule 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)

Is this workflow right for me? 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! 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.

Help! Running the server redirects all requests to index.html! In your .timplaconfig.js config, please set development.middlewareConfig.connectHistoryApiFallbackMiddleware to true. Alternatively, providing a browsersync.proxy config disables this automatically for you.

BrowserSync serverStatic option doesn't work! I'm not able to see my statically served files when visiting their urls. Please make sure that the `browserSync.serveStatic` uses absolute paths. You may use `path.join(__dirname, [youroutdir])` for example to get the full path based on the location of your config.

Gulp? Task runners are no longer required! 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. Although gulp plugins are long past their debut, most of them are still relevant to our tasking needs. Gulp is useful as it opens up streams to BrowserSync and Webpack.

Gem/plugin/package X provides webpack middleware... Yes, there are packages, gems or composer plugins that allow injecting webpack via middleware into your asset pipeline. 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! Also, we often get into the framework-exclusivity. Think of Timpla as a consistent tool to bring over to projects.

How different is this from Blendid? After a fork to upgrade dependencies, it was decided to branch out to provide an updated and extensive configuration framework.

Does it optimise images or fonts? 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.

Why not inject stylesheets? Critical-css, lesser requests through service workers / caching and css-in-html have benefits too :)

Is this production ready? 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!

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!

cd [timpla folder] npm install npm run lib:start cd [your project] npm link timpla

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

Releasing the plugin