Front-end development toolkit, powered by Webpack, Babel, CSS Modules, Less, ESLint, Prettier, Jest and Storybook.
Quickly get up and running with a zero-config development environment, or optionally add minimal config when needed. Designed for usage with seek-style-guide, although this isn't a requirement.
This tool is heavily inspired by other work, most notably:
WARNING: While this software is open source, its primary purpose is to improve consistency, cross-team collaboration and code quality at SEEK. As a result, it’s likely that we will introduce more breaking API changes to this project than you’ll find in its alternatives.
Create a new project and start a local development environment:
$ npx sku init my-app
$ cd my-app
$ npm start
Don't have npx?
$ npm install -g npx
Modern Javascript (via Babel)
Use import
, const
, =>
, rest/spread operators, destructuring, classes with class properties, JSX and all their friends in your code. It'll all just work, thanks to the following Babel plugins:
- @babel/preset-env
- @babel/preset-react
- @babel/preset-typescript
- @babel/plugin-proposal-object-rest-spread
- @babel/plugin-proposal-class-properties
- babel-preset-react-optimize
If you'd like use a package that requires adding a Babel plugin, try Babel Macros. Macros allow packages to apply the configuration changes for you when they are imported. For example, to use Emotion:
import styled from 'react-emotion/macro';
import { css } from 'emotion/macro';
Lots of packages support macros, and their documentation is best place to look for help.
TypeScript files (.ts
and .tsx
) are supported as part of your source code. You can also mix JavaScript with TypeScript allowing you to slowly convert your project to TypeScript over time. The sku lint
script will report any type errors in your code.
Note: Test files do not support TypeScript.
Locally Scoped CSS (via CSS Modules and Less)
Import any .less
file into your Javascript as a styles
object and use its properties as class names.
For example, given the following Less file:
.exampleWrapper {
font-family: comic sans ms;
color: blue;
}
You can then import the classes into your JavaScript code like so:
import styles from './example.less';
export default () => <div className={styles.exampleWrapper}>Hello World!</div>;
Static CSS-in-JS (via css-in-js-loader)
You can import .css.js
files into your components and use them exactly as you would a regular style sheet. This is mostly useful when you want to take advantage of JavaScript to compose styles:
import { standardWrapper } from 'theme/wrappers';
import { fontFamily } from 'theme/typography';
import { brandPrimary } from 'theme/palette';
export default {
'.exampleWrapper': {
...standardWrapper,
fontFamily: fontFamily,
color: brandPrimary
}
};
import styles from './example.css.js';
export default () => <div className={styles.exampleWrapper}>Hello World!</div>;
Unit and Snapshot Testing (via Jest)
The sku test
command will invoke Jest, running any tests in files named *.test.js
, *.spec.js
or in a __tests__
folder.
Since sku uses Jest as a testing framework, you can read the Jest documentation for more information on writing compatible tests.
Note: sku
will forward all command line args to jest
.
Example running tests in watch mode:
$ sku test --watch
If you need to set up your test framework, you can provide a setupTests
script in your config:
module.exports = {
setupTests: 'src/setupTests.js'
};
For example, if you're using Enzyme, your setupTests
script would look like this:
import 'jest-enzyme';
import { configure } from 'enzyme';
import Adapter from 'enzyme-adapter-react-16';
configure({ adapter: new Adapter() });
Running sku lint
will execute the ESLint/TSLint rules over the code in your src
directory, depending on the type of file. You can see the ESLint rules defined for sku projects in eslint-config-seek. Similarly you can see the TSLint rules defined in tslint-config-seek.
Running sku format
will format all JavaScript and TypeScript files in your project using Prettier, and fix ESLint errors where possible. As changes to formatting are considered non-breaking, please ensure you run sku format
after upgrading sku
.
Files can be excluded from formatting by adding paths into the .prettierignore
file.
Static Pre-rendering (via html-render-webpack-plugin)
Generate static HTML files via a webpack-compiled render function that has access to your application code. For example, when building a React application, you can pre-render to static HTML with React's renderToString function.
See the static-rendering docs for more detail.
Component Explorer via Storybook
Running sku storybook
will open up a local component explorer, displaying all component instances declared in files named *.stories.js
, for example:
import { storiesOf } from 'sku/storybook';
import React from 'react';
import Button from './Button';
storiesOf('Button', module)
.add('Primary', () => <Button variant="primary">Primary</Button>)
.add('Secondary', () => <Button variant="secondary">Secondary</Button>);
NOTE: To access the Storybook API, you should import from sku/storybook
, since your project isn't depending on Storybook directly.
By default, Storybook runs on port 8081
. If you'd like to use a different port, you can provide it via the storybookPort
option in sku.config.js
:
module.exports = {
storybookPort: 9000
};
SEEK Style Guide Support
Without any special setup, sku is pre-configured for the SEEK Style Guide. Just start importing components as needed and everything should just work out of the box.
To start a local development server and open a new browser tab:
$ npm start
To run tests:
$ npm test
To build assets for production:
$ npm run build
If you need to configure sku, first create a sku.config.js
file in your project root:
$ touch sku.config.js
While sku has a zero configuration mode, the equivalent manual configuration would look like this:
module.exports = {
clientEntry: 'src/client.js',
renderEntry: 'src/render.js',
public: 'src/public',
publicPath: '/',
target: 'dist'
};
If you need to specify a different config file you can do so with the --config
parameter.
$ sku start --config sku.custom.config.js
NOTE: The --config
parameter is only used for dev (sku start
) and build steps (sku build
). Linting (sku lint
), formatting (sku format
) and running of unit tests (sku test
) will still use the default config file and does not support it.
At any point in your application, you can use a dynamic import to create a split point.
For example, when importing the default export from another file:
import('./some/other/file').then(({ default: stuff }) => {
console.log(stuff);
});
For dynamically loaded bundles to work in production, you must provide a publicPath
option in your sku config.
For example, if your assets are hosted on a CDN:
module.exports = {
...,
publicPath: `https://cdn.example.com/my-app/${process.env.BUILD_ID}/`
};
By default, process.env.NODE_ENV
is handled correctly for you and provided globally, even to your client code. This is based on the sku script that's currently being executed, so NODE_ENV
is 'development'
when running sku start
, but 'production'
when running sku build
.
Any other environment variables can be configured using the env
option:
module.exports = {
...
env: {
MY_ENVIRONMENT_VARIABLE: 'hello',
ANOTHER_ENVIRONMENT_VARIABLE: 'world'
}
}
Since this config is written in JavaScript, not JSON, you can easily pass through any existing environment variables:
module.exports = {
...
env: {
BUILD_NUMBER: process.env.BUILD_NUMBER
}
}
Environment variables can also be configured separately for development and production, plus any custom environments. The default environment for sku build
is production
, however you can select a custom environment to build your application by passing the command line argument --env
(-e
for shorthand). The environment is also passed to your code using process.env.SKU_ENV
. Please note that these environments are not related to NODE_ENV
.
sku build --env testing
module.exports = {
...
env: {
API_ENDPOINT: {
development: '/mock/api',
testing: 'http://localhost/test/api',
production: 'https://example.com/real/api'
}
}
}
Note: Running sku start
will always use the development
environment.
Since sku injects its own code into your bundle in development mode, it's important for polyfills that modify the global environment to be loaded before all other code. To address this, the polyfills
option allows you to provide an array of modules to import before any other code is executed.
Note: Polyfills are only loaded in a browser context. This feature can't be used to modify the global environment in Node.
module.exports = {
...,
polyfills: [
'promise-polyfill',
'core-js/modules/es6.symbol',
'regenerator-runtime/runtime'
]
}
By default, sku expects your source code to be in a directory named src
in the root of your project. If your source code needs to be arranged differently, you can provide a srcPaths
array:
module.exports = {
...,
srcPaths: [
'src',
'docs/src'
]
}
Sometimes you might want to extract and share code between sku projects, but this code is likely to rely on the same tooling and language features that this toolkit provides. A great example of this is seek-style-guide. Out of the box sku supports loading the seek-style-guide but if you need to treat other packages in this way you can use compilePackages
.
module.exports = {
compilePackages: ['awesome-shared-components']
};
Any node_modules
passed into this option will be compiled through webpack as if they are part of your app.
If you need to build a UMD library instead of a web site, you can provide a library
entry and libraryName
option instead:
modules.exports = {
libraryEntry: 'src/library.js',
renderEntry: 'src/render.js',
libraryName: 'MyAwesomeLibrary'
};
Your library
entry must export its public API via a default export:
export default () => {
console.log('Hello from my library!');
};
Note that, in this scenario, the render
entry is only used to provide a development environment. No HTML will be generated when running sku build
.
Out of the box sku will start your app with webpack-dev-server on http://localhost:8080. However there a few options you can pass sku.config.js
if needed.
module.exports = {
// A list hosts your app can run off while in the dev environment.
hosts: ['dev.seek.com.au', 'dev.seek.co.nz'],
// The port you want the server to run on
port: 5000,
// Optional parameter to set a page to open when the development server starts
initialPath: '/my-page'
};
Note: The app will always run on localhost. The hosts
option is only for apps that resolve custom hosts to localhost.
The default mode for sku is to statically render projects. However, Server-Side Rendering (SSR) can explicitly be turned on, both in development with hot module reloading for React, and in production.
First, you need to create a sku.config.js
file, which will contain the following setup at minimum:
module.exports = {
clientEntry: 'src/client.js',
serverEntry: 'src/server/server.js',
public: 'src/public',
publicPath: '/',
target: 'dist',
port: 3300,
serverPort: 3301
};
If you have an existing configuration, for example generated with sku init
, you will need to replace the render
entry point by a server
entry point, and add port info as documented above.
Then, you need to create your server
entry. Sku will automatically provide an Express server for the user. The entry point for SSR, server
, is used to provide a render callback and any additional middlewares to that server. You can provide either a single middleware or an array. This can be done as follows:
import render from './render.js';
import middleware from './middleware';
export default ({ publicPath, headTags, bodyTags }) => {
renderCallback: (req, res) => {
res.send(render(publicPath, headTags, bodyTags));
},
middleware: middleware
};
Last but not least, please note that commands for SSR are different to the ones used normally:
- Use
sku start-ssr
to start your development environment. It uses bothport
andserverPort
to spin up hot module reloading servers. - Use
sku build-ssr
to build your production assets. You can then runnode ./dist/server.js
. Your server will run athttp://localhost:xxxx
, wherexxxx
isserverPort
. - Use
sku test-ssr
to test your application
Refer to CONTRIBUTING.md. If you're planning to change the public API, please open a new issue and follow the provided RFC template in the GitHub issue template.
MIT License