CityOfBoston/311 - Githubissues

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 dev http://localhost:3000/
React Storybook: npm run storybook http://localhost:9001/
Gulp: npx gulp watch
Tests: npm test or npm test -- --watch
Lint: npm run lint (uses ESLint --fix to 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.sample to .env and fill in the endpoint and keys
Get other API keys: Mapbox, Searchly, &c. and put them in .env
npm install
npx gulp watch
npm 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.