meetup-web-platform
v7.1.1775
Published
A collection of Node web application utilities developed for the Meetup web platform
Downloads
136
Readme
Web platform
This is the base platform for serving Meetup web apps including the public website and admin. It provides a Hapi webserver and a set of conventions for composing applications with React + Redux.
In general, application-specific code will live outside of this package.
Docs
- App configuration management
- Auth flow from
requestAuthPlugin
- Analytics/tracking
- Application state management
- Rendering in consumer applications
- Caching - API and static assets
Public modules
- Routing module
- Language plugin for Hapi
- API proxy plugin for Hapi
- Click and Activity tracking
- API State module
- 'Query': structuring data requests - GET/POST/PATCH/DELETE requests to REST API
- Redux store modules - browser and server
Releases
This package uses semver versioning to tag releases, although the patch version
is determined exclusively by the Travis build number for pushes to master
.
Major and minor versions are hard-coded into the Makefile.
Manual pushes to master
and PR merges to master will be built by Travis, and
will kick off the yarn publish routine. The currently-published version of the
package is shown on the repo homepage on GitHub in a badge at the top of the
README.
Development/Beta releases
When developing a consumer application that requires changes to the platform code, you can release a beta version of the platform on npm by opening a PR in the meetup-web-platform repo. When it builds successfully, a new beta version will be added to the list of available npm versions. The generated version number is in the Travis build logs, which you can navigate to by clicking on 'Show all checks' in the box that says 'All checks have passed', and then getting the 'Details' of the Travis build.
At the bottom of the build log, there is a line that echo
s the GIT_TAG
.
If you click the disclosure arrow, the version number will be displayed, e.g.
0.5.177-beta
.
You can then install this beta version into your consumer application with
> yarn install meetup-web-platform@<version tag>
Each time you push a change to your meetup-web-platform
PR, you'll need to
re-install it with the new tag in your consumer application code.
The overall workflow is:
- Open a PR for your
meetup-web-platform
branch - Wait for Travis to successfully build your branch (this can take 5+ minutes)
- Get the version string from the build logs under
GIT_TAG
- (if needed) Push changes to your
meetup-web-platform
branch - Repeat steps 2-3
Introductory Resources
Basic knowledge of reactive programming using RxJS 5 is a pre-requisite for being able to work in this repository. https://www.learnrxjs.io/ manages a good list of starting resources, specifically:
- RxJS Introduction - Official Docs
- The Introduction to Reactive Programming You've Been Missing - André Staltz
- Asynchronous Programming: The End of The Loop - Jafar Husain
- Introduction to Reactive Programming - André Staltz
- Functional Programming in Javascript - Jafar Husain
Suggestions:
- Reference the api docs regularly while watching videos (http://reactivex.io/rxjs/).
- Play around with the JSBin in the egghead.io videos (
console.log
to each transformation step, etc).
Modules
Server
The server module exports a startServer
function that consumes
a mapping of locale codes to app-rendering Observables, plus any app-specific
server routes and plugins. See the code comments for usage details.
Client
Rendering 'empty' state with <NotFound>
To correctly render a 'not found' state for a feature, you should render a
<NotFound>
component, which the server will use to set the response status to
404.
Example:
import NotFound from 'meetup-web-platform/lib/components/NotFound';
class GroupContainer extends React.Component {
render() {
if (!this.props.group) {
return (
<NotFound>
<h1>Sorry, no matching group was found</h1>
</NotFound>
);
}
return <GroupDetail group={this.props.group} />;
}
}
Tracking
Activity tracking happens on every HTTP request, and is tagged with
platform: 'WEB',
platform_agent: <read from package.json:config.agent>
The platform also tracks clicks similar to Meetup classic.
More info in Confluence here
Dev patterns
Async
Use Promises or Observables to handle async processing - the latter tends to provide more powerful async tools than the former, particularly for long processing chains or anything involving sequences of values, but Promises are good for single async operations. Do not write functions that fire callbacks.
When using Observables, you can always throw
an Error and expect the
subscriber to provide an onError
handler. When using Promises, call
Promise.reject(new Error(<message>))
and expect that the caller will
provide a .catch()
or onRejected
handler.
Error Handling
Guidelines:
- Use
Error
objects liberally - they are totally safe until they are paired with athrow
, and even then they can be usefully processed without crashing the application with atry/catch
. - Use
throw
when there is no clear way for the application to recover from the error. Uncaught errors are allowed to crash the application and are valuable both in dev and in integration tests. - Populate state with the actual
Error
object rather than just a Boolean or error message String. Error objects provide better introspection data. For example, a validation process might returnnull
(for no validation errors) ornew Error('Value is required')
rather thantrue
(for "is valid") orfalse
. - Many errors will have an associated Redux action, such as
LOGIN_ERROR
- keep the corresponding state updates as narrow as possible. For example,LOGIN_ERROR
should only affectstate.app.login
- all affected UI components should read from that property rather than independently responding toLOGIN_ERROR
in a reducer. Do not create a high-levelerror
properties state - When using Promises or Observables, always provide an error
handling function (
catch
for Promises,error
for Observables)