All the best places to go to when you are in the Twin Cities (for the Super Bowl).
The default gulp develop
will not get new data from Airtable, nor will it create the responsive images. So, to make these things happen specifically, use the following:
gulp source:data
gulp assets:responsive:images
, gulp assets:responsive:airtable
gulp assets:responsive:videos
You should only have to run these when you have updated content.
In order to publish and build everything from scratch, run the following (note that it will take some time to run all this, specifically the publishing will take some time unless you have done it before on your computer):
gulp deploy --production
See the following resources to test attributes.
The following are global prerequisites and may already be installed.
brew install node
npm install gulp -g
AIRTABLE_API_KEY
: The Airtable API key used to get data from the spreadsheets.ffmpeg
brew tap varenc/ffmpeg && \
brew tap-pin varenc/ffmpeg && \
brew install ffmpeg --with-libvpx --with-libvorbis --with-fdk-aac --with-opus;
# This will install all extensions (probably not needed)
brew install ffmpeg $(brew options ffmpeg | grep -v -e '\s' | grep -e '--with-\|--HEAD' | tr '\n' ' ');
The following should be performed for initial and each code update:
npm install
To run a local web server that will auto-reload with Browsersync, watch for file changes and re-build: gulp develop
config.json
: Non-content config for application.
config.custom.json
if there is a need to add configuration that should not be put into revision history.content.json
: See Content and copy. This file is used to hold content values, such as a site-wide title or description.templates/
: Holds HTML templates. Any files in here will get run through EJS templating and passed values from config.json
, content.json
, package.json
, and data from the Airtable data source.
templates/layout.*.ejs.html
: These are the files that get rendered with the data described above and correlate to a file or set of files rendered in the build.templates/_*.ejs.html
: These are includes used to help separate out and reuse parts.styles/
: Styles in SASS syntax.
styles/index.scss
: Main point of entry for styles.styles/_*.scss
: Any includes should be prefixed with an underscore.app/
: Where JS logic goes. This supports ES6+ JS syntax with Babel and gets compiled with Webpack.
app/index.js
: Main entry point of application.app/svelte-components/*
: Svelte components. These get rendered in the template/layout process as well as brought in on the client side.assets/
: Various media files. This gets copied directly to build.sources/
: Directory is for all non-data source material, such as wireframes or original images. Note that if there are materials that should not be made public, consider using Dropbox and make a note in this file about how to access.lib/
: Modules used in building or other non-data tasks.tests/
: Tests for app; see Testing section below.The majority of content is managed in this Airtable. Use the following command to get new data from the Airtable, saved as sources/guide-data.json
:
gulp source:data
Note that the gulp develop
process does not automatically download new data as it would be slow to run every time, which means you will have to manually run the above command.
Depending on what libraries or dependencies you need to include there are a few different ways to get those into the project.
npm
.npm install --save awesome-lib
import awesome from "awesome-lib";
awesome.radical();
config.json
. Consider using the StribLab static libs CDN."js": {
"globals": [
"https://cdnjs.cloudflare.com/ajax/libs/pym/1.1.2/pym.v1.min.js"
]
}
/* global Pym */
tests/global.js
utils.js
module file, just use a relative path to include it:
import utilsFn from "./utils.js";
let utils = utilsFn({});
npm
.npm install --save normalize-scss
@import "normalize-scss/sass/_normalize.scss";
config.json
. Consider using the StribLab static libs CDN."css": {
"globals": [
"https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css"
]
}
Testing is run via Jest. Fast, unit and higher level testing will happen on build. You can run these test manually with gulp js:test
or npm test
.
Acceptance testing (i.e. high level quality assurance) is done separately as running headless Chrome takes more than a couple seconds. You will need a new version of Chrome or Chrome Canary installed, then run js:test:acceptance
.
NOTE: Acceptance test will fail until this fix is published.
TODO: Some basic automated, cross-browser testing would be very beneficial. Unfortunately things like Browserstack are very expensive, and managing our own servers to do this would be very expensive time-wise as well.
A manual test page is provided for looking at the piece embeded in another page.
gulp develop
cd tests && python -m SimpleHTTPServer
or http-server ./tests/
All parts are compiled into the build/
folder. The default complete build can be done with gulp
or gulp build
Deployment is setup for AWS S3. Set the following environment variables; they can be set in a .env file as well. For further reading on setting up access, see Configureing the JS-SDK.
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_PROFILE
AWS_CONFIG_FILE
To deploy, run gulp deploy
. This will build and publish to the location configured as default
(see Configuration below).
To deploy to the production
location, for instance, simply use that flag like: gulp deploy --production
A handy command is to use gulp publish:open
to open the URL to that project.
Publishing is configured in the config.json
file. The publish
property can have the following keys: default
, testing
, staging
, and production
. It is suggested to use default in place of the staging
as the default gets used when no flag is specified (see below). Each key should correspond to an object with bucket
, path
, and url
. IMPORTANT: The url
should be a fully qualified URL that ends with a /
. This URL will get inserted into some meta tags on the page by default. For example:
{
"publish": {
"default": {
"bucket": "static.startribune.com",
"path": "news/projects-staging/all/super-bowl-guide/",
"url": "http://static.startribune.com/news/projects-staging/all/super-bowl-guide/"
},
"production": {
"bucket": "static.startribune.com",
"path": "news/projects/all/super-bowl-guide/",
"url": "http://static.startribune.com/news/projects/all/super-bowl-guide/"
}
}
}
Using the flags --testing
, --staging
, or --production
will switch context for any relevant publish
or deploy
commands. Note that if the flag is not configured, the default
will be used.
The publishing function, uses a token that helps ensure a name collision with another project doesn't overwrite files unwittingly. The publishToken
in config.json
is used as an identifier. This gets deployed to S3 and then checked whenever publishing happens again. The gulp publish
(run via gulp deploy
) will automatically create this token if it doesn't exist.
If you see an error message that states that the tokens do not match, make sure that the location you are publishing to doesn't have a different project at it, or converse with teammates or administrators about the issue.
Having a consistent style for code and similar aspects makes collaboration easier. Though there is nothing that enforces these things, intentionally so, spending some time to adhere to these styles will be beneficial in the long run.
.eslintrc
.
.styleintrc
.
Other good practices that are not encompassed with linters.
class
es instead of id
s for HTML elements, specifically for styling and JS.rem
, em
, vh
, vw
, or %
, instead of absolute values such as px
. This helps accessibility as well as designing for different screen sizes.rem
for "component" level styling, such as a form, and then use em
for styling inside components.Code is licensed under the MIT license included here. Content (such as images, video, audio, copy) can only be reused with express permission by Star Tribune.
Generated by Star Tribune StribLab generator.