The source code for the future 311.boston.gov.
Developers
This is a Node project using the Next.js framework for server-side rendering.
- Development Server:
npm run devhttp://localhost:3000/ - React Storybook:
npm run storybookhttp://localhost:9001/ - Gulp:
npx gulp watch - Tests:
npm testornpm test -- --watch - Lint:
npm run lint(uses ESLint--fixto fix common style errors) - Typecheck:
npx flow
Getting started
Make sure you have at least Node 8.2 installed, preferrably with nvm or
equivalent so you automatically pick up our .nvmrc file. Also, npm >= 5.3
(installed by default with Node 8.2 and up) and gulp-cli.
- Get the Open311 api_key and URL from a friend
- Copy
.env.sampleto.envand fill in the endpoint and keys - Get other API keys: Mapbox, Searchly, &c. and put them in .env
npm installnpx gulp watchnpm run dev- Visit http://localhost:3000/ in your browser
JavaScript
This project uses Babel at the “latest” preset to include ES2015–17, as well as the “next/babel” preset.
Please make full use of:
- Object rest spread:
{ foo: 1, ...bar } - Async functions:
async (promisedNum) => (3 + await promisedNum) - Class properties:
class MyComponent { onClick = () => { this.setState({ clicked: true })} }
Code style is enforced by ESLint, which can be run (in --fix mode) with
npm run lint. Committed code must contain no errors or warnings. On a per-file
basis, certain errors may be turned off. For example, to keep a class-based
component:
// eslint react/prefer-stateless-function: 0
Type-checking
We use Flow type checking to ensure that modules are integrated together
in a typesafe way. All source, test, and story files should start with
// @flow to enable type checking.
We use flow-typed to provide Flow
types for supported NPM modules, and have added our own under /flow-typed/npm.
We use apollo-codegen to
generate Flow types for the *.graphql queries and mutations in
/store/modules/graphql. These are output as
/store/modules/graphql/schema.flow.js and should be used when possible to
establish types for GraphQL arguments and responses.
Run npx flow to check types.
Backend
This project starts a Hapi server and uses Next.js’s custom server & routing support to serve HTML and JS. It runs the Apollo GraphQL server to facilitate communication with the client code.
Server-only code, including the GraphQL schema and resolvers, is in the
/server directory.
The Gulp graphql:schema and graphql:types tasks are automatically run by
gulp watch to update the schema and type files when code in server/graphql
changes.
Backend debugging with Charles:
env NODE_TLS_REJECT_UNAUTHORIZED=0 http_proxy=http://localhost:8888/ npm run dev
Frontend
The Next.js framework turns components in the /pages directory into entry
points for the app. These are wrapped in higher-order components to provide
common setup for our store and Glamor CSS setup.
The MobX store is configured in the /data/store directory. Access to the
GraphQL backend is mediated through the function modules in /data/dao.
Components and containers are organized under /components by page.
For UI-focused development, use React Storybook by
running npm run storybook and visiting http://localhost:9001
Local use of patterns library: After running gulp and npx fractal start -- --watch in the patterns directory, change stylesheets.json to
reference https://localhost:3001 instead of cob-patterns-staging.
Public domain
This project is in the worldwide public domain. As stated in LICENSE:
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.
Contributions
If you're interested in helping this project, there are three ways to help. Be sure to checkout our Guide to Contributing.