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
=>, 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:
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:
Lots of packages support macros, and their documentation is best place to look for help.
TypeScript files (
sku lint script will report any type errors in your code.
Note: Test files do not support TypeScript.
CSS Modules and Less)Locally Scoped CSS (via
styles object and use its properties as class names.
For example, given the following Less file:
.exampleWrapperfont-family: comic sans ms;color: blue;
;<div className=stylesexampleWrapper>Hello World!</div>;
You can import
;;;'.exampleWrapper':...standardWrapperfontFamily: fontFamilycolor: brandPrimary;
;<div className=stylesexampleWrapper>Hello World!</div>;
Jest)Unit and Snapshot Testing (via
sku test command will invoke Jest, running any tests in files named
*.spec.js or in a
Since sku uses Jest as a testing framework, you can read the Jest documentation for more information on writing compatible tests.
sku will forward all command line args to
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:
moduleexports =setupTests: 'src/setupTests.js';
For example, if you're using Enzyme, your
setupTests script would look like this:
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.
sku format after upgrading
Files can be excluded from formatting by adding paths into the
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.
sku storybook will open up a local component explorer, displaying all component instances declared in files named
*.stories.js, for example:
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
moduleexports =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:
moduleexports =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
$ sku start --config sku.custom.config.js
--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:
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:
moduleexports =...publicPath: `/`;
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
'development' when running
sku start, but
'production' when running
Any other environment variables can be configured using the
moduleexports =...env:MY_ENVIRONMENT_VARIABLE: 'hello'ANOTHER_ENVIRONMENT_VARIABLE: 'world'
moduleexports =...env:BUILD_NUMBER: processenvBUILD_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
-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
sku build --env testing
moduleexports =...env:API_ENDPOINT:development: '/mock/api'testing: ''production: ''
sku start will always use the
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.
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
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
moduleexports =compilePackages: 'awesome-shared-components';
node_modules passed into this option will be compiled through webpack as if they are part of your app.
Building a Library
If you need to build a UMD library instead of a web site, you can provide a
library entry and
libraryName option instead:
modulesexports =libraryEntry: 'src/library.js'renderEntry: 'src/render.js'libraryName: 'MyAwesomeLibrary';
library entry must export its public API via a default export:
Note that, in this scenario, the
render entry is only used to provide a development environment. No HTML will be generated when running
moduleexports =// 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 onport: 5000// Optional parameter to set a page to open when the development server startsinitialPath: '/my-page';
Note: The app will always run on localhost. The
hosts option is only for apps that resolve custom hosts to localhost.
Server-Side Rendering Support
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:
moduleexports =clientEntry: 'src/client.js'serverEntry: 'src/server/server.js'public: 'src/public'publicPath: '/'target: 'dist'port: 3300serverPort: 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:
Last but not least, please note that commands for SSR are different to the ones used normally:
sku start-ssrto start your development environment. It uses both
serverPortto spin up hot module reloading servers.
sku build-ssrto build your production assets. You can then run
node ./dist/server.js. Your server will run at
sku test-ssrto test your application