starbase is an offline-first web app boilerplate that is built with webpack 4, PostCSS & Babel 7. Get up and running in minutes using some of the most powerful front-end tools available in 2018:
- Node.js & Yarn
- webpack 4 & webpack-dev-server
- Babel 7 w/ ESLint
- PostCSS w/
- ...and more!
starbase is intended to be relatively small in scope so that it may be easily extended and customized, or used as a learning tool for folks who are trying to become familiar with webpack 4, PostCSS and/or ES6.
starbase is open source and free software, so you may to do whatever you wish with it -- commercially or personally. You can buy me a beer next time you're in Boston, star the project and tell a friend, or you can erase all signs of origin and tell your coworkers that you made it yourself. It's all good!
After completing the steps below, you will be ready to begin using starbase:
- Install Node.js (latest LTS recommended)
- Install Yarn
- Clone starbase into your project root directory
- Install dependencies by running
yarnin your project root directory
Note: if you hate Yarn for some reason, you can skip Step 2 and use
npm install instead of
yarn in Step 4.
building, watching & developing
npm run watch in the project root, your
/src code will be served at the url above and watched for changes. As you modify code in
/src, the project will be recompiled and your browser will refresh to show the latest changes.
cd /path/to/starbase npm run watch
building for production
npm run build in your project root to run a production build.
Production builds compile & minify your assets into
/dist for distribution and/or integration into whatever codebase you'll be using these assets in.
cd /path/to/starbase npm run build
features you may want to remove
The assets generated by starbase are hashed (strings injected into the filenames) as a cache-busting mechanism. JS and CSS assets will receive a new filename for each production build, but other assets (fonts, images, etc) will only be updated when they are modified.
This feature ships with webpack (and the loaders we use), so removing it is pretty straightforward. Simply open up the webpack config files and remove the hashes from the filenames, which should look something like this:
Removing hashing for production builds is not recommended.
starbase is setup to clear all contents of
/dist (where compiled assets are piped into) during each
npm run build. If you'd like to remove this part of the build process, perform the following steps:
CleanWebpackPluginfrom the plugins array in
CleanWebpackPluginas a requirement at the top of
- remove the
Removing the cleanup process means that deleted assets in
/src will not be deleted in
/dist until you manually do so. I recommend keeping the cleanup process intact unless you have a specific reason not to, such as having un-managed assets in
fetch & promise polyfills
Because starbase was built to accommodate ES6 & CommonJS (and not jQuery) it is assumed that you'll be using fetch for asynchronous requests.
If you want to remove these for any reason, perform the following steps:
yarn remove es6-promise whatwg-fetchin the project root to remove the dependencies
- remove the lines in
/src/app.jsthat fall under the "fetch & promise polyfills" comment (it'll be obvious which ones)
Note: if you think you might use fetch in the future, comment-out the requires instead of deleting them. Commented-out code is not included in production builds.
features you may want to customize
/.stylelintrc respectively) included out of the box contain some basic common rules. Modify them to your liking to encourage consistent code throughout your project.
airbnb eslint config
/.eslintrc file. I've included a couple basic overrides (in
/.eslintrc) to demonstrate usage.
to remove the airbnb eslint config:
/.eslintrc, remove the line that says
/package.json, remove the
npm updateif you hate yarn)
After completing the steps above, the only rules that eslint will enforce are the ones you define in the
rules object in
service worker caching
starbase uses offline-plugin to cache your project assets for offline use. This means that if someone visits your website on a device that supports service workers, they will be able to view your project again, even if their device is offline.
Out of the box, starbase caches everything, because the project is less than 50kb total. If you will be making a larger app, be considerate of your users and limit what you cache-- perhaps avoid caching large images, custom fonts, etc. Check out the options docs for offline-plugin to learn more.
Service workers, by design, only function on secure (https) environments. There is no issue with running starbase on an http environment-- the service worker will simply not be utilized.
You may see an info log entry in your console from
offline-plugin while using the
watch command, feel free to ignore this.
offline-plugin is not utilized on the dev server because it doesn't always play nice with
webpack-dev-server. It is intentionally only utilized in production builds.
to remove offline-plugin:
/package.json, remove the
/webpack/webpack.config.base.js, remove all references to
/src/app.js, remove the
importstatement that references
There is no consequence to removing this feature, besides limiting offline access to your project.
to disable (but not delete) offline-plugin:
You can disable
offline-plugin without deleting it from your codebase, so that it's not included in your production code (reduces filesize) but is ready to be re-enabled if you ever want it back.
/src/app.js, comment-out the
importstatement that references
features you may want to know about
global css variables
starbase supports global CSS variables via the :root pseudo-element, which can be found in
/src/variables/variables.css. You can split your variables into multiple files, and just import them into
/src/variables/variables.css if you'd like them to be more granular.
These variables automatically injected into any CSS in the
/src/app directories, so they are always available for use in your app & component stylesheets.
Each component that comes with Starbase uses at least one variable to demonstrate the functionality.
All variables are cleaned up in your production code and only the values will remain, so there is no bloat or downside to using these variables. Go nuts!
html webpack plugin
starbase uses HTML Webpack Plugin to generate HTML assets. The reason for this is to allow webpack to manage other assets, such as favicons and embedded images, as part of the build process. Adding new templates (pages) is very easy, but you'll need to read the official plugin docs for the latest info.