🚀 About
Do we need another universal Javascript boilerplate/framework? Probably not. Because there are already some pretty good one's out there.
But we @AnotherState felt that we needed some more control over our pipeline, builds and configuration, in order to handle our different clients cases.
Therefore we created our own, we borrowed a little here, get inspiration from over there, and we created our own perspective and implementation from it.
Since we all love our fellow coder's and have used other people's code over the years, we wanted to give something back to the community. So here we have, use it like you want - and give us an shout if you are missing something, or have ideas for future implementations
💥 Setup
Out of the box, you will get an boilerplate of @AnotherState's prefered setup, but this can easily be updated.
npm install tobie -g
cd your-app
tobie setup
💯 Features
Tobie comes prebuilt with some nice features, where you can kickstart your development phase with no configuration at all but are in the same time highly customised. Tobie are shipped with React, but with some basic configuration you could use your prefered render framework.
- Hot Module Replacement
- Server side rendering (SSR)
- Static site generator
- Environment variabels (Just create an .env in root dir, or use tobie.config.js)
- CSS/SCSS Modules
- Babel
- Prettier
- Stylelint
- Eslint
- Flow
- React
- Jest / Jest puppeteer
- Storybook
- Loadable components
🎨 Getting started
Start your development process
yarn dev or tobie dev
Build your bundle
yarn build or tobie build
Start storybook
yarn storybook or tobie storybook
Run Jest test
yarn test or tobie test
Run Integration tests
yarn test-integration or tobie test-integration
✨ Documentation
Tobie are highly customised and can easily be modified to fit your needs. To extend our webpack configuration, create and tobie.config.js in your project.
Tobie support out-of-the-box some linters/type checkers/code formatters. Just drop the specific .conf file in project root, and Tobie will pick it up.
- Babel (.babelrc)
- Stylelint (.styleintrc)
- Flow (.flowconfig)
- Prettier (.prettierrc)
- Eslint (.eslintrc)
Almost everything in your build process can be customised in Tobie. Place an .env in projetct root, or use tobie.config.js to override Tobies defualts:
MANIFEST: Name of assets manifest (mainfest.json)
PUBLIC: Name of the build dir (./build)
PORT: Which port Tobie should serve from (3000)
DEV_PORT_CLIENT: Tobie serves client assets at a different port in dev mode (3001) (Only use when server-rendering)
STORYBOOK_PORT: Storybooks dev port (3002)
PUBLIC_PATH: Specify assets public path (/)
DEV_HOST: Specify your host (localhost || 0.0.0.0)
🎨 Render
By default Tobie handles the basic stuff out of the box. But your are able to override it's defaults. By adding an client.js / server.js / index.html you can control your entry points. You can watch the default's in Tobie src file
- client.js
- server.js
- index.html (Client)
- index.html (Server)
To render your content in HTML Tobie uses an HTML template file which will inject your code/markup by default.
Client
From the box, Tobie will automatically create an client.js entrypoint for your application. The project entrypoint are in that way App.js placed in the src dir. If you wish to override the default client.js just override it by creating one in root src dir.
Server
In the same way, the server.js and server side rendering are by default handled by Tobie. Override this implementation by placing an server.js file in src. The default server.js will use an Express server together with Helmet. In dev mode Tobie uses Nodemon, to refresh your code changes behind-the-scenes.
HTML
If you whish to override Tobie's default HTML implementation just place an index.html file in src dir. Please be aware that when running Tobie's in SSR mode you will need to place an es6 template string inside your root element: <div id="root">${markup}</div>
Prerender
When setting the flag app: 'prerender' in tobiee.config.js render block, Tobie will use react-snap to create your static pre rendered HTML files. To override Tobie's default configuration for react-snap, define your react-snap configuration instead of the boolean flag for the crawl property, like so: crawl: {
minifyHtml: {
collapseWhitespace: false,
removeComments: false
}
Envs
Use the env object in tobie.config.js to specify environment variables during compile time. Tobie will substitue those with the specified ones. You could also create an .env file next to your package.json and it will be picked by Tobie, in the same way.
Styles
Tobie supports css, scss and css modules from scratch. To use css modules just name your file to *.module.(css|scss), and Tobie will parse it the correct way.
✔️ Tests
Tobiee comes shipped with Jest (unit test) and Jest puppeteer (integration test).
Loadable components
Tobiee comes prepacked and configured to use Loadable Components.
To split your chunks, just use import your components like so; loadable(() => import('@Containers/Docs')); and loadable components/ tobiee will take care of the rest. Visit their docs for more information, and how it works behind the scenes.
Unit test
All files in the source directory name *.test.{js|jsx|mjs} will parsed and use for unit testing. For creating custom configuration, place a jest.config.js in project root, and it will be merged with Tobie's predefault one.
Integration test
Tobie uses Jest Puppeteer to run integration test's. All files places under src directory named *.test.integration.{js|jsx|mjs} will be used in the integration tests. Along with starting Jest puppeteer (as an headless Chrome), Tobie will also start the dev server to run the integration test's against. For creating custom configuration, add a jest-puppeteer.config.js in project root, and it will be merged with Tobie's predefault one.
Examples
tobie.config.js
module.exports = {
// Specify how you want to render your app
render: {
// Valid options are 'ssr' || 'prerender' || 'client' - default are 'ssr'
app: 'ssr',
// Specify your root element
rootElement: 'root'
},
// Want to pass in some dynamic vars to your application? Either set it here, or create an .env in project root
env: {
// Will be processed as: process.env.HELLO, and will be subst at compile time
HELLO: 'world'
},
// Merge Tobies webpack with your project
merge(config, target, environment) {
// config: Tobies webpack object
// target: 'client' or 'server'
// environment: 'production' or 'development'
config.resolve.alias['@App'] = __dirname;
return config;
}
};
🏆 Inspiration
We previously used Razzle as our prefered setup, which is awesome but since maintaince were down for a while, and needs to have our own custom one, we humbily borrowed and used a lot from there, so if you like Tobie, please give a shout out to the team over there.
Development process
To run/debug Tobie at your local workspace, start with:
npm link [Tobie path]