Stripped-down, modernized (as of April 2016) version of the American Panorama template. This template/boilerplate offers a starting point for creating applications that use components from Stamen's Panorama toolkit. It is built using React, Redux, and React Router, but uses only a minimal subset of offerings from each. While designed to be used with Panorama toolkit, at it's heart it's really just a React project template, and can be used with or without the Panorama components.
Ensure that your Node version matches that present in .nvmrc.
nvm is the easiest way to do this on Mac, nvm-windows on Windows. Installation instructions are in each of those links.
To use nvm to switch Node versions:
$ nvm install
Found '/Users/ericsoco/stamen/panorama-template/.nvmrc' with version <5.9.1>
######################################################################## 100.0%
Now using node v5.9.1 (npm v2.11.3)NOTE: you'll need to run nvm install (or nvm use) in each shell instance.
Make sure you have npm installed. Note: version > 2.7.0 is required to install scoped packages, such as @panorama/toolkit. Instructions for updating npm are here.
Load required npm modules.
npm installTo run locally:
npm startOpen browser to http://localhost:8888/
To use development code: Copy the build directory to your server, but for production you will want to run:
npm run dist
This will create a dist directory. Move this directory to your server.
Both directories are all static files, so no special server requirements needed.
If you're deploying to a path other than '/', use the --baseUrl parameter when running a build script (e.g. npm run dist). In order for react-router to resolve routes correctly, its history instance must be set up with the correct basename. With a basename set up, static resouces at relative paths (e.g. stylesheets and scripts loaded from index.html) will not load correctly when one or more paths deep in the application/router URL. So, we complement react-router's basename with a <base> tag, and set href to the same value (i.e. <base href="https://github.com/stamen/panorama-template/blob/master/<baseUrl>">).
This is an issue when deploying to studio.stamen.com; therefore, there is already an npm script set up to make this easier in package.json, called dist-studio. Modify the --baseUrl param value accordingly to use it.
The baseUrl value gets written to a node environment variable when running locally (served via gulp-connect), hardcoded into the compiled application with loose-envify, and written to index.html using gulp-html-replace.
The template is written in ES6, and compiled down to ES5 via Babel. All of the application setup happens in main.jsx.
A single Redux store and action creator are instantiated there, and passed down into the application. They are passed through the React component tree, available as props (in a component, as this.props.store and this.props.actions, respectively). This pattern allows the application to be used in a server-rendering context as well, keeping application state separate for each session. Reducers live in reducers.js, and the action creator exists within actions.js.
React Router acts as the primary framework within which applications using this template are built. The router configuration (mapping of paths to views) exists within the React render() call in main.jsx. Router views are generally defined within ./src/views/, while local components (those not imported from Panorama) live within ./src/components/. This runs parallel to the concept of "container and presentational" components.
The template uses gulp-json-sass to allow variables to be shared across Sass and JavaScript. Variables added to variables.json can be imported into JavaScript files. The project build compiles them into Sass variables, which are imported from variables-derived.scss. Examples of this exist within App.jsx and _layout.scss.
The template uses a slightly modified Sass version of Skeleton. To minimize the compiled CSS footprint, comment out any unused Skeleton modules in _skeleton.scss.