starbase

starbase is a website boilerplate built with webpack 5, modern JS (via Babel) & Sass that enables developers to get up and running in minutes using some of the most powerful front-end tools available in 2021:

starbase is intended to be 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 5, Sass and/or modern JS.

license

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!

getting started

After completing the steps below, you will be ready to begin using starbase:

Install Node.js (latest LTS recommended)
Clone starbase into your project root directory
Install dependencies by running npm install in your project root directory

building, watching & developing

local development

starbase uses webpack-dev-server to serve up your project at http://localhost:8080 for streamlined and convenient development.

After running npm run start 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 start

building for production

Use 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

asset hashing

The assets generated by starbase are hashed (strings injected into the filenames) as a cache-busting mechanism. Hashes are generated based on file contents so they will only change when the files themselves have changed -- so caching won't be broken entirely.

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: .[hash:8].

Removing hashing for production builds is not recommended.

build-time cleanup

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:

remove CleanWebpackPlugin from the plugins array in /webpack/webpack.config.prod.js
remove CleanWebpackPlugin as a requirement at the top of /webpack/webpack.config.prod.js
remove the CleanWebpackPlugin dependency from /package.json

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 /dist.

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.

Fetch is supported in all modern browsers, but some old dogs still don't support it and that's what we need the es6-promise & whatwg-fetch polyfills for.

If you want to remove these for any reason, perform the following steps:

remove es6-promise & whatwg-fetch from /package.json
remove the relevant imports in /src/app.js

features you may want to customize

root path

starbase is setup to run with assets referenced via relative paths so generated .html files can be opened locally. If you plan on deploying to a web server, it'll be a good idea to set the publicPath in /webpack/webpack.config.base.js.

This variable should be set to / if the app will run at the root of a domain or subdomain, or to /folderName (example) if it'll be deployed to a subfolder.

javascript & css linting

starbase uses ESLint for Javascript (ES6) linting and stylelint for CSS linting. The configs (/.eslintrc.js and /.stylelintrc.js 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

starbase enforces the Airbnb JavaScript Style Guide with ESLint via eslint-config-airbnb. These rules are basically the industry standard in 2017 so I'd recommend adhering to them, but you can override individual rules via the project /.eslintrc.js file. I've included a couple basic overrides (in /.eslintrc.js) to demonstrate usage.

to remove the airbnb eslint config:

in /.eslintrc.js, remove the line that says extends
in /package.json, remove the eslint-config-airbnb dependency
run npm update

After completing the steps above, the only rules that eslint will enforce are the ones you define in the rules object in /.eslintrc.js.

prettier js formatting

starbase uses Prettier to enforce and simplify code consistency. If you use VS Code, check out the Prettier VS Code extension.

features you may want to know about

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.

LockeAG/starbase