This repository is for the Street Support website, found at https://streetsupport.net. The website helps people facing homelessness find services in their area, as as well as sign-posting people wanting to help, to where it is needed. The site acts as a gateway into Street Support's broader remit of helping connect organisations, people with lived experience, policy-makers, and businesses to co-produce lasting solutions.
I will be adding any updates we receive from our users as issues on Github. Please fork and work in the develop branch. Once the update is completed, submit a pull request into develop. Travis CI automatically builds on each commit to develop, uat and prod.
I would also appreciate any issues/PRs for bugs you may come across, and general fixes/refactorings. Where possible, please write a test that covers your code change.
- develop: https://ssn-web-dev.azurewebsites.net/ -
- release: https://streetsupport.net -
- Install Node 18 (recommended, especially for ARM Macs),
- In your command line terminal, navigate to the street support project folder,
- Run:
npm i - Run gulp using
npx gulp(no need to install gulp globally)
See Installation Troubleshooting section if Installation fails
See https://github.com/fephil/garrus for more information about the Frontend workflow.
In your editor of choice, the following plugins are recommended but not required. Note the plugin names might be slightly different depending on your editor.
- editorconfig,
- tabs-to-spaces,
- linter,
- linter-handlebars,
- linter-js-standard,
- linter-stylelint.
Run these tasks in your command line Terminal:
gulp [--production] [--debug]
gulp deploy [--production] [--debug]
gulp auditcode
- The
gulptask builds the website, watches for changes and starts up a sever, - The
gulp deploytask builds the website without watching for changes or running the server, - The
gulp auditcodetask runs various linting on the project source files, - The
gulp jsdevtask only checks and builds javascript with associated tests, - The
--productionflag builds minified assets with no sourcemaps, - The
--debugflag shows the files being created in each task (if the task has a pipe).
There are four API environments. You can alter the API your local instance is running from by editing /blob/develop/src/js/env.js:
- 0: locally running API instance
- 1: CI/Dev
- 2: Staging/UAT
- 3: LIVE
Day-to-day development should point at CI (value 1).
On running the default gulp task from the terminal, it will run tests and linting, build the site into the /_dist/ directory, and then launch in your default browser. As you edit files in the /src/ directory, the site will refresh automatically.
Each page of the site is found under the /pages/ directory. Each page is represented by a handlebars file index.hbs, in a directory named after the page's url. In each .hbs file, meta data is entered to define the page:
- title: the page's title tag
- description: the page's meta description
- layout: the master layout file (found in
/layouts/) - permalink: ???
- jsBundle: the js bundle that will be loaded into the page. Bundles are defined in
/webpack.config.jsand each one points to a js file in/src/js/. For basic pages, usegeneric. - section: the top level navigation item this page belongs to. See
/src/scss/modules/_variables.scssfor list of sections - page: the navigation item for this page. See
/src/scss/modules/_variables.scssfor list of pages
Page templating is done using Hogan. Note: template parts need to be escaped eg:
\{{myVariable}}
Knockout data-binding is also used in some pages.
Page code-behinds are written in plain ol' Javascript, or use Knockout. Knockout view models are found in /js/models/ are mostly tested. ES2015 syntax is transpiled using Babel.
Tests reside in the /spec directory, and are written using Jasmine and Sinon. Please ensure any features submitted via pull request are covered by tests.
A number of happy paths are covered by automated browsers tests at: https://github.com/StreetSupport/web-automated-testing.
CSS styling is written in SCSS, based on Susy, in the BEM style, and is auto-prefixed. Build with a mobile-first approach, using sass-mq for media queries. Each component's styles should reside in its own file. Avoid nesting of elements and modifiers (although there are many cases of nesting at the moment!).
gulp[62193]: ../src/node_contextify.cc:631:static void node::contextify::ContextifyScript::New(const FunctionCallbackInfo<v8::Value> &): Assertion `args[1]->IsString()' failed.
Caused by: One of gulp's dependencies are out of date
Solution: Uninstall and reinstall Node Modules
rm -rf node_modules
npm i
ERROR in Missing binding <PROJECT_DIR>/node_modules/node-sass/vendor/darwin-x64-11/binding.node
Node Sass could not find a binding for your current environment: <ENVIRONMENT> with Node <NODE_VERSION>
Caused by: switching node versions
Solution: Rebuild Project
npm rebuild
Caused by: network blocking download
Solution: use an alternative network (best to run npm i before attending)
spawn /Users/.../node_modules/pngquant-bin/vendor/pngquant ENOENT
Error: pngquant failed to build, make sure that libpng is installed
Unknown system error -86
Caused by: The pre-built binaries for image optimization tools (pngquant, optipng, mozjpeg, gifsicle) are compiled for x86 and don't run natively on ARM Macs.
Solution: Install Rosetta and use an x86 version of Node:
# Install Rosetta
softwareupdate --install-rosetta --agree-to-license
# If using nvm, uninstall your current Node 18 and reinstall under Rosetta
nvm uninstall 18
arch -x86_64 zsh -c 'source ~/.zshrc && nvm install 18'
# Then reinstall dependencies
rm -rf node_modules
npm install
If there are problems that aren't mentioned here, post in the slack channel so we can help out and update these docs.
