RCA-Precursor

Quick start guide

Precursor is designed to take the pain away from webpack configurations and isomorphic complexities, leaving you with a super simple source folder with only the files you need. The chosen tech stack has been tried and tested at RCA, and is extensible and highly configurable, whilst having a small footprint in your codebase.

Starting a new project

Grab the latest seed project from the RCA-Seed-app repository.

$ git clone [email protected]:craig-collie/rca-seed-app.git

Since rca-precursor is already a dependency in the seed project, you should only need to:

$ yarn
$ yarn start

And finally visit http://localhost:3000 in your browser.

Migrating your project to Precursor

If you're feeling game enough to migrate, then simply add rca-precursor as a dependency, and follow the migration documentation (that hasn't been written yet).

$ yarn add rca-precursor

Configuration

Required settings

appName

The name of your application.

entry

Configure your webpack bundles using the entry configuration.

{
  entry: {
    main: './utils/client.js',
  }
}

root

Default: ./src/App.js

The root application component. By default, this component receives serverProps which is any resolved route data.

import React from 'react';

const App = serverProps => (
  <div>
    //...
  </div>
);

export default App;

routes

An collection of routes that both the server and client will both used. Routes follow the standard react-router guidelines for defining a route. These rounds should be exported as an array.

export default [
  {
    path: '/',
    exact: true,
    component: //...,
  },
  {
    path: '/pages/:pageId',
    component: //...,
  },
  {
    path: null,
    component: //...,
  },
];

Environment flags

isDevEnvironment

_Default: _process.env.NODE_ENV

Sets a flag against the current NODE_ENV allowing for both express and webpack to run in production mode.

Bundle output

context

Default: <root>/src/

The contextual path of your application source folder.

distOutput

Default: /public

The output folder that is created and published to when building and deploying your application.

jsPath

Default: /js

The output folder for all bundled javascript.

cssPath

Default: /css

The output folder for all bundled CSS.

publicPath

Default: /

A prefix that is added to all outputted assets, generally used when you need to configure a CDN.

indexFile

Default: index.html

The index filename of your application

Plugin settings

localIdentName

The className output for CSS-Modules

Routes

Getting started

Routes are the pages of your application, and usually require a few properties to ensure they work correctly. Each Route should contain the path property, which defines the URL path. For example, consider http://www.myapp.com/admin, to ensure your admin route is visible when the user visits that URL, the following route would need to be created:

{
  path: '/admin',
  exact: true,
  component: AdminContainer,
},

In this route definition, the path and exact properties ensure that when the user visits http://www.myapp.com/admin this route is visible, and that the AdminContainer component is rendered.

Creating a route component (Container)

Route components, or Containers are the components that render routes for your application. Containers are the components that connect to your external API's and provide data to any components that live inside them. Each Container you create comes with some additional static methods and properties that allow you to express how data is requests and cached.

Consider the below example:

import React, { Component } from 'react';
import PropTypes from 'prop-types';

// Any service that performs an ajax request
import fetchService from './fetchService';

class RouteContainer extends Component {
  static getInitialProps = () => fetchService()
  static cache = true

  render() {
    const { data } = this.props;
    return (
      <div>
        // ...
      </div>
    );
  }
}

export default RouteContainer;

This Container is a standard, stateful React Component with the addition of the static getInitialProps method, which requests the fetchService(). This fetchService is completely made up at this state, and we don't need to know how it connects to an API, rather, we just need to know that it does.

static getInitialProps() [Promise<expression>]

When defining your Container, including this static method will ensure that whatever request is required to be called, it is called and the response is returned BEFORE the rendering of this route. This means that if your Route requires things to be rendered based on some data that comes back from fetchService() then all of the rendering will be done first, before it is visually available to your user.

Why is this a good thing?

You don't necessarily need to do this in your application, however if you prefer to present visually complete pages to your user, or have concerns around SEO, it can usually be a good idea request first, and present later.

After making this initial request, the data returned from that initial call will yield this.props.data in your Container.

static cache [boolean]

Every single time a Route is rendered, it will refresh it's data, and call the static getInitialProps method. If this is something you want to avoid, in which case stale data isn't a concern to you, then add the static cache = true property to your Container.

Technology Stack

| Tech | Description | | --- | --- | | Node | JavaScript runtime build on Chrome's V8 JavaScript engine. | | Express | Fast, un-opinionated, minimalist web framework for Node.js | | Webpack | Asset bundling | | Babel | Use next generation JavaScript today | | React | A JavaScript library for building user interfaces | | CSS-Modules | Locally scoped interoperable CSS | | PostCSS | CSS Pre-processing (using SASS syntax) and autoprefixing |