This is the source code for learning.mozilla.org, using learning.mofostaging.net as staging server.

For a summary of the most recent changes to the project, please see CHANGELOG.md. It's awesome.

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 the site 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 [email protected]:mozilla/learning.mozilla.org.git
cd learning.mozilla.org

To start developing, all you need to do is run the following in the learning.mozilla.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.

Because this project uses a variety of tools that transform the original source code before delivering it to the browser, it is critical for source maps to work properly in order to ensure a pleasant developer experience.

However, due to the unfortunate realities of software development, there isn't a "one size fits all" solution to this. Please be sure to read the Environment Variables section below and configure your environment as needed to ensure that you're seeing useful line numbers for whatever part of the codebase you need to change.

JS

• lib/: Non-react modules, as well as entry-point modules like main.jsx and routes.jsx
• components/: Re-usable react components that can be used throughout the site
• pages/: React "page" components, i.e. top-level pages required by lib/router
• hoc/: React higher-order components

Less

• less/: This is where you should add styles. common.less is the entry-point.

Other

• gulp/: build tasks used for running the site, as well as testing
• build/: used as a staging area when the site gets built
• test/: For js tests, manual tests
• img/: For images
• dist/: Generated site assets goes here. This folder is gitignored, do not edit files here.

Work in progress, but please read the documentation on how we are doing it for the site 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.

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.

Each test file should end with .test.js or .test.jsx and will be automatically discovered by the test runner.

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.

For detailed information about manual testing, see the Manual Testing section of CONTRIBUTING.md.

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.

See the Environment Variables section below for more details.

The following environment variables can be used to modify how the software works.

Create a file called .env in the root of your project, and then add all the environment variables you need into this using the following format:

export GA_ACCOUNT='xxxxxxx'
export TEACH_API_URL='xxxxxxx'

These are environment variables that turn on experimental features that need to be tested in a staging environment but should not show up on a production deploy. These flags need to explicitly be set for the feature to show up.

The current list of feature flags is:

If you run into CORS or CSP issues (blocked domains trying to GET or POST, loading external scripts like X-Ray Goggles, etc) then you probably want to make sure that the Content Security Policy is set to clear whatever it is you need cleared.

We handle this in app.js, in the helmet.contentSecurityPolicy block. Typically you'll care about the connectSrc block for remote content fetching, and the scriptSrc block for injecting/loading external scripts, although you might have CSP needs outside those two categories: all of the major CSP categories have their own section and should be readily identifiable.

The site can also be served through a lightweight server which dynamically generates requested HTML files. This feature is currently experimental. For more information on the rationale behind it, see #585.

To run the server in development mode, use npm run app. The server-side page rendering code will be dynamically updated as relevant files are changed.

For production deployment, you will need to:

1. Set NODE_ENV=production and other relevant environment variables and then re-run npm install. This will build all static assets that won't change during production.

2. Run node app.js.

The server is also designed to be easily deployable on Heroku.

• Roadmap
• Change Log
• Contribution Guidelines