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
- Configuring Timpla
- The three levels of reloading
- Common setups
- Common Problems
- CAQIAs (Commonly asked questions I ask)
- Developing 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!
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.
# Base install npm i --save-dev timpla webpack @babel/core # Timpla allows you to bring in your own versions of the following modules! 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 # Install typescript dependencies as well. You may skip this part of you only wish to build JS scripts. npm i --save @babel/preset-typescript @types/react @types/react-dom typescript tslint tslint-config-prettier tslint-react fork-ts-checker-webpack-plugin # Initialise timpla # Careful: outputs config files and a starter src directory: # babel.config.js # .eslintrc # .prettierrc # .timplaconfig.js # The following are generated for TS projects # tsconfig.json # tslint.json # For TypeScript support (DEFAULT) npx timpla init # For JS-only, disabling TypeScript support npx timpla initJS # 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
andstatic
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
# 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:
# You package.json file
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:
// @ts-check /** * The @type annotations are harmless, vscode might just make your life easier * by adding intellisense support whilst you type! */ const configure = moduleexports =
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:
/** The partialised Timpla Config so users' may opt in to only customise what they wish to. */
The timplaHelper object
The following variables are available from the timplaHelper
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.
const debug = processenvDEBUG === 'timpla'const isProduction = processenvNODE_ENV === 'production' moduleexports = 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'
Configuring Webpack
Webpack by default uses the following plugins (module.rules):
# 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:
// .timplaconfig.js // ... the rest of your config file javascripts: const modifiedConfig = ...webpackConfig // You can modify the config to how you want it // check if it's prod or development if timplaProcessisProduction // do this; if timplaProcessisDevelopment // do this // or even modify rules & plugins... modifiedConfigplugins = modifiedConfigplugins modifiedConfigmodulerules // 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.
// ... the rest of your timpla config stylesheets: // ... the rest of your stylesheets config const stylesheetsConfig = timplaConfigstylesheets // access the stylesheets config const paths = src: dest: // We must return a higher order function return { // 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 // finds [your-project]/stylesheets/something.txt // transfers the file to [your-project]/stylesheets/somethingelse.txt // 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 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.
moduleexports = 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:
// .timplaconfig.jsconst configure = const 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 toconst proxyTarget = 'http://127.0.0.1:7025' // Access the site via localhost:localhostPortconst 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' moduleexports =
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!
// make sure to run npm i --save gulp-liquidr firstconst configure = const liquidr = const changed = moduleexports =
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 installnpm 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
- Make changes
- pr > Commit those changes to a separate PR
- pr > Make sure Travis turns green
- master > Merge PR
- master > Bump version in package.json
- master > npm run lib:changelog (needs to be installed first)
- master > npm run lib:docs (builds the ts-docs and readme files)
- master > Commit package.json and docs, README.md and CHANGELOG.md files
- master > Tag
- master > Push
- npm publish