Rollbar is an error-logging service we use through our web apps to view and debug errors in real-time. The implementation is pretty easy and supports a large number of languages. There are two types of implementations for Rollbar, browser
and server
.
Implementing Rollbar generally requires the inclusion of the respective rollbar module (browser/server) and then initializing the rollbar object with account credentials.
Access Token
Browser Token
Environment (Staging/Production)
Payload (data to be analyzed)
Browser Setup DOC
Browser implementation tracks a user's actions through the Application/Webpage (DOM) and reports a significant amount of steps before the error occurs; displaying the output (DOM/text) the user sees when the error is triggered. In our WebApps we include the rollbar in the module that constructs the page's HTML structure, ie. services-js/[service-name]/pages/_document.tsx
. A browser implementation looks like this:
Server Setup DOC
Our code base abstracts the server (Hapi.js) implementation on a top layer module at modules-js/hapi-common/src/hapi-common.ts
, here it expands the reporting tool to handle 404 errors as well among other things. Although reporting an error only requires the error message/payload, rollbar.error(error)
going forward we should be more verbose in the errors we log; rollbar.error(e, request.raw.req)
Ex.
Server Usage
Single Page Application (SPA)
Our web apps are Single Page Apps
, SPAs, meaning that it all runs off of the same front-end code even when the URL subpage and parameters change. Since we include Rollbar at the top of the Application it is available through the browser's window
DOM object or by including it as a module in specific sections. DOM window
is sufficient for our needs so the example below covers how to raise an error from within the app.
Rollbar has an implementation for PHP, like others it's straightforward to implement, but it is missing a documented implementation for Drupal. There is a Rollbar module on Drupal.org that is installed with composer
but this will require more insight/research.
PHP Implementation
In Composer
Setup
Send an Error and a Message
Above we went through how to set up Rollbar in the codebase, however, we also need to set up a project for each implementation in the Rollbar dashboard.
Login into the account
Create New Project
Invite team members
Setup Notifications - Determine if you are using Slack or email, etc
Integrate with Source Control Provider - We have a couple of apps (DBConnector) that are hosted in AWS, for this we'll need to set it up using this doc
Setup Versions and Deploy controls - Setup a way to notify Rollbar of an AWS deployment (Lambda)
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
id
string
ID of the cake to get, for free of course.
recipe
string
The API will do its best to find a cake matching the provided recipe.
gluten
boolean
Whether the cake should be gluten-free or not.
Authentication
string
Authentication token to track down who is emptying our stocks.
Emotion is a tool for doing CSS-in-JS • https://emotion.sh
Emotion is our styling tool of choice for webapps. Use Emotion if you need CSS styles that aren’t in or appropriate to put in Fleet.
CSS-in-JS is attractive for us because it lets us write CSS that is co-located with our React components. Emotion styles are scoped to the component where they’re used, so it’s very easy to reason about the effects changing the styles would cause.
We picked Emotion over Next.js’s default styled-jsx because the latter is still reliant on user-generated class names to associate styles with components, which means that you a) have to come up with them; b) risk conflicting with other class names; and c) don’t get automatic dead code detection the way you do when you stop referencing an Emotion style.
We have two helpers that make using Emotion better and safer.
The jest-emotion
package interprets Emotion class names in Jest snapshots (such as those generated by StoryShots). It unrolls the CSS so that it gets diffed in the snapshot. Without it, CSS changes only appear in the snapshots as generated class name changes.
We use the eslint-plugin-emotion
package with ESLint to enforce setting the proper /** @jsx jsx */
pragma and @emotion/core
import statements when the Emotion 10 css
prop is used (see below).
Emotion does have two Babel plugins, but we’ve decided against using them. The babel-emotion
plugin generates slightly nicer class names and can make source maps. The @emotion/babel-preset-css-prop
preset includes babel-emotion
and also automatically uses the @emotion/core
jsx
factory for all JSX so you can use css
props.
We like to avoid Babel plugins because they introduce magic that can be hard to track down. We’re much happier with the solution of having eslint-plugin-emotion
add /** @jsx */
pragmas for us, since it’s nearly as automatic but significantly more transparent as to what’s happening.
Emotion released a new version, 10, that makes use of a JSX factory to support a css
prop on React components. When styles are applied via the css
prop, no extra work needs to be done to automatically inject <style>
elements for server-side rendering.
Currently, all of our webapps use the emotion
package, which uses the pre-10 API. With this API, the css()
method returns a string for the style’s auto-generated class name. We use these values in className
attributes in the JSX, often in template literals when they are composed with other class names. These apps also have code in _document.tsx
and _app.tsx
to handle the server-side rendering (and to set up a CacheProvider
for legacy compatibility).
react-fleet
has been updated to use css()
from @emotion/core
, which generates a style object that needs to get applied via the css
prop. It is therefore ready for when we start using the version 10 API in our apps.
It would be nice in general to use version 10 because that lets us remove the awkward SSR support. Given the backwards compatibility interface of the emotion
package, it’s not worth actively converting old apps. New apps, however, should start from the ground-up using the css
prop.
Using Storybook to develop and document UI components
Storybook lets us:
quickly build UI components in isolation
mock out a component’s different states/variations
experiment and test with different props (i.e. what happens if the text for a label is really, really long?)
It also:
provides documentation of our components
is used by Percy to perform its visual diffs
If you write a Story for every different use case or state of a component, Percy will take a snapshot and catch any visual changes later on.
If you group any Stories (i.e. Group|Folder/Story) in your Storybook, Stories without a defined group will now appear in an automatically-generated "Others" group in the sidebar.
You can have multiple storiesOf
blocks if it helps you stay organized; any blocks that share a name string will be combined in the sidebar as a single collection of Stories.
The Knobs addon lets us change the props passed into our component inside Storybook’s UI. It’s super helpful to quickly test out component appearance against different values.
You can also use Knobs to add buttons that trigger a change in UI:
works with Jest to do automatic code snapshot testing ()
can catch simple a11y violations as soon as they occur ()
Good for components that stretch too wide without a container. Using , all of the Stories will be children of the wrapper component.
Documentation: