This is an initial attempt at implementing the Webmaker Learning website.
This software consists of two major parts:
- A static site generator that creates a number of
index.html
files in various directories which can be viewed in any browser, including ones that don't support JavaScript. - Client-side JavaScript code that progressively enhances the user experience based on browser capabilities.
It should be noted that, based on the product roadmap, the static site generator may eventually evolve into becoming a dynamic server.
To get a local version of teach.webmaker.org running, you'll need to have git and node installed on your local machine.
In order to contribute to this project, you'll need to create your own fork of it and make pull-requests against our master branch.
Clone from your own fork or from the original:
git clone git@github.com:mozilla/teach.webmaker.org.git
cd teach.webmaker.org
To start developing, all you need to do is run the following in the teach.webmaker.org
directory you just created:
npm install
npm start
This will start a webserver for you at http://localhost:8008
, and run a watch
process so that your front-end assets will be regenerated as you make changes.
JS
lib/
: Non-react modules, as well as entry-point modules likemain.jsx
androutes.jsx
components/
: Re-usable react components that can be used throughout the sitepages/
: React "page" components, i.e. top-level pages required bylib/router
mixins/
: React mixins
Less
less/
: This is where you should add styles.common.less
is the entry-point.
Other
test/
: For js tests, manual testsimg/
: For imagesdist/
: Generated site assets goes here. This folder is gitignored, do not edit files here.
Fully testing the code is accomplished by running npm test
,
which exercises a number of different aspects of the
codebase described below.
This generates a full static site and ensures that no React warnings are raised. react-a11y is used to ensure that no accessibility issues are present.
Individually running only the smoke test can be accomplished
via npm run smoketest
.
Unit tests are spread across two different testing environments.
Both environments use the mocha test runner and should for assertions.
These tests generally exercise the code of the static site generator
and are located in the test
directory.
Each test file should end with .test.js
and will be automatically
discovered by the test runner.
Individually running only the node unit tests can be accomplished
via node_modules/.bin/mocha test/*.test.js
. For more options,
see the documentation for mocha (1).
These tests exercise the code that runs in the user's browser. They're
located in the test/browser
directory.
Browser test files are not automatically discovered and should
be explicitly require
'd in test/browser/main.js
.
Individually running only the browser unit tests can be accomplished
by first running npm start
and then visiting http://localhost:8008/test/
in your browser.
Run npm run build
to generate a static site in dist/
that
doesn't require any client-side JavaScript. This static
site also uses history.pushState
for navigation if the browser
supports it.
For reference, a recent static build of the site can be found at teach.mofostaging.net.
The static site can also be deployed to S3 via npm run s3
, but
this requires setting at least a few environment variables. See
the Environment Variables section below for more details.
The following environment variables can be used to modify how the software works.
Note: When an environment variable is described as representing a boolean value, if the variable exists with any value (even the empty string), the boolean is true; otherwise, it's false.
Name | Description |
---|---|
WEBPACK_DEVTOOL |
determines the setting for the devtool Webpack option. It defaults to source-map ; if you're on Firefox, though, you may want to set it to eval so that console logging statements originate from useful line numbers. For re details on the trade-offs between different options for development, see our conversation on sourcemaps. |
AWS_ACCESS_KEY |
is the Amazon Web Services access key used when uploading to s3 via npm run s3 . |
AWS_SECRET_KEY |
is the Amazon Web Services secret key used when uploading to s3 via npm run s3 . |
AWS_BUCKET |
is the S3 bucket to upload to when using npm run s3 . It defaults to teach.mofostaging.net . |
AWS_REGION |
is the S3 region to upload to when using npm run s3 . It defaults to us-east-1 . |
ORIGIN |
is the domain name of which the site is hosted. It defaults to https://teach.webmaker.org . This is used in situations where absolute URLs are required, such as generating a sitemap.xml file. |
MAPBOX_ACCESS_TOKEN |
is the Mapbox access token to use for embedded maps in the website. Optional. |
MAPBOX_MAP_ID |
is the Mapbox map ID to use for embedded maps in the website. Optional. |
TEACH_API_URL |
is the origin of the Teach API server. Defaults to https://teach-api.herokuapp.com . |
GA_ACCOUNT |
is the property ID of the Google Analytics account. E.g. UA-123... . Optional. |
First, create a .env
file in the root of your project:
export GA_ACCOUNT='xxxxxxx'
export TEACH_API_URL='xxxxxxx'
Then run source .env
before running npm start
.
Note: If you're on Windows, this won't work, and you'll likely
want to create a batch file that uses
setx.exe
.