This repository contains the source code for WeeWikiPaint, the application being developed in the series.
(Wondering why we check in things like
node_modules or IDE settings? See "The Reliable Build".)
Before building or running for the first time:
- Install Node.js
- Install Git
- Install Firefox (for smoke tests)
- Install geckodriver into path (for smoke tests). On Mac, this is most easily done with Homebrew:
brew install geckodriver. On Windows, download geckodriver and manually add it to your path. On Linux, either download geckodriver manually or use your favorite package manager.
- Clone source repository:
- All commands must run from root of repository:
Note: If you update the repository (with
git pull or similar), be sure to erase generated files with
git clean -fdx first. (Note that this will erase any files you've added, so be sure to check in what you want to keep first.)
Running old episodes:
Every episode's source code has an associated
episodeXX tag. You can check out and run those episodes, but some episodes' code won't work on the current version of Node. You'll need to install the exact version of Node the code was written for.
To check out an old episode:
- If you made any changes, check them in.
- Erase generated files:
git clean -fdx
- Reset any changes:
git reset --hard
- Check out old version:
git checkout episodeXX(For example,
git checkout episode200.)
- Episodes 1-9 don't work on case-sensitive file systems. To fix the problem, rename
Jakefile.js(with a capital 'J').
- Episodes 37-39 don't work on Windows. A workaround is included in the episode 37 video.
- Episodes 269-441 and 469+ may fail when running smoke tests. They use Selenium for smoke testing and download the appropriate Firefox driver as needed. Those drivers may be missing or incompatible with your current version of Firefox. Starting with episode 469, Selenium uses geckodriver, which is installed separately from the rest of Selenium, which may make the smoke tests more reliable.
To change Node versions and run the code:
Look at the
package.jsonto see which version of Node the code runs on. Prior to episode 31, the Node version was documented in
readme.md. Prior to episode 10, the version wasn't documented; those episodes used v0.6.17.
To see how to run the code, look at the episode's
readme.mdor watch the episode in question. Note that some episodes end with non-working code.
Known version issues:
Node has introduced breaking changes with newer versions. Here are the issues we're aware of. I've included some workarounds, but the best way to run old code is to install the exact version of Node that the code was written for.
Some episodes include a version of Jake that doesn't run on Node 0.10+. You might be able to resolve this problem by running
npm install jake.
Some episodes include a version of NodeUnit that relies on an internal 'evals' module that was removed in Node 0.12. (See Node.js issue #291.) You might be able to resolve this problem by running
npm install nodeunit.
Some episodes include a version of Testacular (now named "Karma") that crashes when you capture a browser in Node 0.10+. There's no easy workaround for this problem, so just install Node 0.8 if you want to run the code in those episodes.
A few episodes rely on a feature of Node.js streams that was removed in Node 0.10. A workaround is included in the video for the episodes in question.
Most episodes have a test that checks how server.close() handles errors. This behavior was changed in Node 0.12, so the test will fail. (In previous versions, it threw an exception, but now it passes an
errobject to the server.close callback.) You can just delete the test in question, or see episode 14 for a workaround.
To build and test this episode:
./jake.sh karma(Unix/Mac) or
- Navigate at least one browser to http://localhost:9876
./jake.sh loose=true(Unix/Mac) or
You can also run
./jake.sh quick loose=true for a faster but less thorough set of tests.
Note: The master branch is not guaranteed to build successfully. For a known-good build (tested on Mac and Windows, and assumed to work on Linux), use the integration branch. To change branches, follow the steps under "Running old episodes" (above), but replace
integration (for the known-good integration branch) or
master (for the latest code).
To run this episode locally:
./jake.sh run(Unix/Mac) or
- Navigate a browser to http://localhost:5000
Note: The master branch is not guaranteed to run successfully. For a known-good build, use the integration branch as described above.
Before deploying for the first time:
- Make sure code is in Git repository (clone GitHub repo, or 'git init' yours)
- Install Heroku Toolbelt
- Sign up for a Heroku account
heroku create <app_name>(requires git repository and Heroku account)
- Search codebase for
weewikipaint.herokuapp.comURLs and change them to refer to
- Push known-good deploy to Heroku:
git push heroku episode321:master
Then, to deploy:
./jake.sh deploy(Unix/Mac) or
jake deploy(Windows) for instructions
Note: The master and integration branches are not guaranteed to deploy successfully. The last known-good deploy was commit 0eabb0cd7b9f16a9375cb8b16a1d449570d23162. We'll establish better deployment practices in a future chapter of the screencast.
Finding your way around:
build: Scripts and utilities used to build and test
design: Initial design concept
generated: Files generated by the build
generated/dist: Distribution files--what actually runs in production
node_modules: npm modules
spikes: One-off experiments
src: All the source code
src/client: Browser-side code
src/client/content: HTML, CSS, images, etc., and CSS tests
src/client/network: Code used to communicate with the server
src/client/ui: Code used to render the UI
src/node_modules: Commonly-used utility modules. Note that these are not npm modules; they are part of the application source code.
src/server: Server-side code
src/shared: Code shared between client and server
Files that start with an underscore are test-related and not used in production.