This starter repo provides a static-site demo hooked up to the cook build process.

Run this in the terminal from your project's root:

npm install
npm run dev

This installs the cook Build dependency and then builds the site locally, which creates the compiled site in /dist and makes it available at localhost:3000, using BrowserSync for live reloading.

There are different modes of viewing the site while working locally.

For both development modes, dev (BrowserSync - live reload) and dev:prod (http-server), the localhost port should be the same. Check the current port value, but by default it should be 3000: localhost:3000

Some site processes do not need to run every time locally, or they only need to run during deployment, etc. To accommodate this, some features are gated behind Node environment variables. Some are already added in the various package.json-style npm run xxxx script calls. Others you may need to manually add to the command line before running your desired Node command.

We currently specify 2 environments via environment variables, development and production. We use these to enable or disable parts of the build process, either from the core build code or custom, user plugins.

In the terminal, most npm run xxxx scripts already set which environment to use. You may also manually set them if necessary, for example: NODE_ENV=development npm run build

In a custom build plugin, you may use them in conditionals: if (process.env.NODE_ENV === 'development') ...

[Note]: There is a third env. value, NODE_ENV=stage, that has its own run script, npm run build:stage, in case you want to add/remove features when deployed to a Firebase stage project. Out-of-the-box, no internal build processes use this, but you are welcome to use it in your own custom-user build plugins.

• Builds /dist
• Copies /src to /dist
• Runs any custom-user before plugins (runs once)
• Loops through each allowed file, modifying file contents per environment rules and plugin actions:
  • Runs any custom-user default plugins (all plugins run per file)
  • Replaces any found es6 template strings with their matching data from the data config reference source
  • Adds missing http:// protocol to external links to avoid them being treated as internal, relative links
  • Replace include placeholders ([data-include]) with their target source
  • Replace inline placeholders ([data-inline]) with their target external source
  • Set <a> tags whose [href] matches the current-page url as 'active' (class="active")
  • Set <a> tags whose [href] includes part of the current-page url as 'active' (class="active-parent")
  • Store link/script files marked for bundling ([bundle]), and replace their 'old' DOM elements with the new bundled-file call
  • Minify the page source (production environments)
  • Optimizes images (Todo)
  • Optimizes SVG (Todo)
  • Uses Babel to convert ES6 to ES5 (Todo)
• Creates sitemap.xml file in /dist
• Create the bundled .css and .js files specified in the file loop.
• Runs any custom-user after plugins (runs once)

Many build settings can be set in the project's /config/main.js instead of trying to find them in the various build-plugin files.

The build process has built-in, default-configuration settings it uses to know where to build the deployable 'production' site code, where to find the source files, etc.

These are user-configurable via the config file: /config/main.js. For more information on how to modify config values, see the Configuration Readme in the config directory.

The result of npm run build (and its environment variants) creates a static website (by default /dist).

Therefore, you may deploy this directory to your project's server setup (FTP, Firebase, etc.)

To facilitate Firebase deployment (either manually or via CI), add deployment scripts to package.json per environment. We recommend this pattern:

"deploy:stage": "npm run build:stage && firebase deploy --project project-name-stage --only hosting",
"deploy:prod": "npm run build:prod && firebase deploy --project project-name-live --only hosting"

The site includes 'helper' NPM-style run scripts that abstract the underlying, verbose execution code into descriptive, easier-to-type tokens. Type these in the terminal via npm run xxxx. As this may change over time, please consult the scripts object in package.json for the up-to-date scripts.

// Build
build          - The cook build process. Use the dev/stage/prod variants, where necessary, to benefit from environment-specific rules.
build:dev      - Build with dev rules
build:stage    - Build with stage rules
build:prod     - Build with prod rules

// Dev
dev            - Runs the site with live-reload (`BrowserSync`)
dev:bundle     - Creates and uses bundled link/script files instead of the normal, non-bundled source files.
dev:fb         - Runs the site with Firebase items enabled (test redirects)
dev:log        - Shows additional logging in the terminal (page-specific build plugin info)
dev:prod       - Runs the site with a simple, static server (`http-server`)

// Reinstall Node Dependencies
reset          - Removes `/node_modules`, `package-lock.json`, and `/dist`, and then runs `npm install`
reset:clean    - Removes `/node_modules`, `package-lock.json`, and `/dist`, but does not run `npm install`
reset:build    - Reinstalls just the cook Build repo (good for updating version), without installing the rest of the project's packages

// Update Node Dependency Versions
update:check   - Checks all `package.json` dependencies for updates
update:fix     - Updates all out-of-date `package.json` dependencies