/isomorphic500

A reference app built with React and Fluxible with babeljs

Primary LanguageJavaScriptMIT LicenseMIT

isomorphic500

Isomorphic500 is a small isomorphic (universal) web application featuring photos from 500px.

It is built on express using React and Flux with yahoo/fluxible. It is developed with webpack and react-hot-loader and written with babeljs with the help of eslint. It supports multiple languages using react-intl.

The intent of this project is to solidify my experience with these technologies and perhaps to inspire other developers in their journey with React and Flux. It works also as example of a javascript development environment with all the cool recent stuff :-)

  • see the demo on isomorphic500.herokuapp.com (with source maps!)
  • clone this repo and run the server to confirm it is actually working
  • edit a react component or a css style, and see the updated app as you save your changes!
  • read on for some technical details

Get help Join the gitter chat or the #isomorphic500 on reactiflux :-)

Clone this repo

Note This app has been tested on node 0.12.x

git clone https://github.com/gpbl/isomorphic500.git
cd isomorphic500
npm install

Start the app

npm run dev

and open localhost:3000.

You can also try the built app:

npm run build   # First, build for production
npm run prod    # then, run the production version

then open localhost:8080.

Table of Contents

Application structure

$ tree src

├── Application.js       # The root Application component
├── actions/             # Action creators
├── app.js               # The Fluxible app
├── assets/              # Dir with static files
├── client.js            # Entry point for the client
├── components/          # React components
├── config.js            # Load the config for dev or prod
├── constants/           # Constants values (e.g. action types)
├── intl/                # intl messages
├── pages/               # Contains components acting as "page" for each route
│   ...
│   └── InitActions.js   # Actions executed when rendering a route
├── public/              # Only in production: contains static assets loaded with webpack
├── routes.js            # Routes config
├── server/              # Server-side-only code
│   ├── ga.js            # Contains Google Analytics code to inject into HtmlDocument
│   ├── intl-polyfill.js # Support for `intl` on node.js
│   ├── HtmlDocument.js  # Components containing  the <html>...</html> page
│   ├── render.js        # Middleware to render HtmlDocument server-side
│   └── setLocale.js     # Middleware to set locale according to browser, cookie or querystring
├── server.js            # Run the express server, setup fetchr service
├── services/            # Fetchr services (e.g. load data from 500px API)
├── stores/              # Flux stores
│   ├── FeaturedStore.js # Contains the photos' ids to display in the featured page
│   ├── HtmlHeadStore.js # Used to keep title and meta tags
│   ├── IntlStore.js     # Stores intl messages and the current locale
│   └── PhotoStore.js    # Store photo objects from 500px
├── style/               # Contains the Sass styles
└── utils/               # Some useful utils
    ...
    └── IntlComponents.js # Wraps react-intl components to use them with ES6 classes and flux stores

The fluxible app

The src/app.js file is the core of the Fluxible application:

  • it configures Fluxible with Application.js as the root component.
  • it registers the stores so they can work on the same React context
  • it adds the fetchr plugin, to share the same API requests both client and server-side
  • it makes possible to dehydrate the stores on the server and rehydrate them on the client

Async data

I used Fetchr and the relative fluxible-plugin-fetchr. Fetchr services run only on server and send superagent requests to 500px.

Router

This app uses fluxible-router for routing. Fluxible-router works pretty well in fluxible applications since it follows the flux paradigm. The Application component uses the @handleHistory decorator to bind the router to the app.

Stores

Instead of directly listening to stores, components use fluxible's @connectToStores decorator: a store state is passed to components as prop. See for example the PhotoPage or the FeaturedPage.

connectToStore can also "consume" store data without actually listening to any store. This is the case of NavBar or LocaleSwitcher.

Resource stores

While REST APIs usually return collections as arrays, a resource store keeps items as big object – like the PhotoStore. This simplifies the progressive resource updates that may happen during the app’s life.

List stores

A list store keeps references to a resource store, as the FeaturedStore holds the ids of the photos in PhotoStore.

The HtmlHeadStore

The HtmlHeadStore is a special store used to set the <head> meta-tags in the HtmlDocument component, during server-side rendering. It is also listened by the Application component to change the browser's document.title.

This store listens to route actions and set its content according to the current route. It also get data from other stores (e.g. the photo's title from the PhotoStore), or the localized messages from the IntlStore.

Internationalization (i18n)

To give an example on how to implement i18n in a React application, isomorphic500 supports English, Italian, Portuguese and French.

This app adopts React Intl, which is a solid library for this purpose.

How the user’s locale is detected

The app sniffs the browser's accept-language request header. The locale npm module has a nice express middleware for that. Locales are restricted to those set in the app's config.

The user may want to override the detected locale: the LocaleSwitcher component set a cookie when the user chooses a language. Also, we enable the ?hl parameter in the query string to override it. Server-side, cookie and query string are detected by the setLocale middleware.

Setting up react-intl

React-intl requires some boilerplate to work properly. Difficulties here arise mainly for two reasons:

  1. React Intl relies on the Intl global API, not always available on node.js or some browsers (e.g. Safari). Luckly there's an Intl polyfill: on the server we can just "require" it – however on the browser we want to download it only when Intl is not supported.

  2. For each language, we need to load a set of locale data (used by Intl to format numbers and dates) and the translated strings, called messages (used by react-intl). While on node.js we can load them in memory, on the client they need to be downloaded first – and we want to download only the relevant data for the current locale.

On the server the solution is easy: as said, the server loads a polyfill including both Intl and the locale data. For supporting the browser, we can instead rely on our technology stack, i.e. flux and webpack.

On the client, we have to load the Intl polyfill and its locale data before rendering the app, i.e. in client.js.

For this purpose, I used webpack's require.ensure() to split Intl and localized data in multiple chunks. Only after they have been downloaded, the app can be mounted. See the loadIntlPolyfill() and loadLocaleData() functions in IntlUtils: they return a promise that is resolved when the webpack chunks are downloaded and required.

They are used in client.js before mounting the app.

Important: since react-intl assumes Intl is already in the global scope, we can't import the fluxible app (which imports react-intl in some of its components) before polyfilling Intl. That's why you see in client.js require("./app") inside the in the renderApp() function, and not as import on the top of the file.

Internationalization, the flux way

Lets talk about the data that react-intl needs to deliver translated content. Translated messages are saved in the intl directory and shared between client and server using the IntlStore.

This store listens to a LOAD_INTL_SERVER action dispatched by IntlActionCreator. We execute this action only server side before rendering the HtmlDocument component together with the usual navigateAction. This allows to dehydrate/rehydrate the store content.

React-intl components need to have access to the IntlStore. Plus, since I'm using ES6 classes, I can't adopt the react-intl Mixin in my components. To solve this, I wrap the Formatted* components and make them available from IntlComponents.

Sending the locale to the API

While this is not required by the 500px API, we can send the current locale to the API so it can deliver localized content. This is made very easy by the Fetchr services, since they expose the req object: see for example the photo service.

Development

Run the development version with

npm run dev

nodemon

This task runs the server with nodemon. Nodemon will restart the server when some of the files specified in its config change.

Webpack

Webpack is used as commonjs module bundler, css builder (using sass-loader) and assets loader (images and svg files).

The development config enables source maps, the Hot Module Replacement and react-hot-loader. It loads CSS styles with <style>, to enable styles live reload). This config is used by the webpack-dev-server, serving the files bundled by Webpack.

The production config is used to build the production version with npm run build: similar to the dev config, it minifies the JS files, removes the debug statements and produces an external .css file. Files are served from a express static directory (i.e. /public/assets).

Both configs set a process.env.BROWSER global variable, useful to require CSS from the components, e.g:

// MyComponent
if (process.env.BROWSER) {
  require('../style/MyComponent.scss');
}

Files loaded by webpack are hashed. Javascript and CSS file names are saved in a JSON file and passed to the HtmlDocument component from the server/render middleware.

Babeljs

This app is written in Javascript-Babel. Babel config is in .babelrc (it only enables class properties). On Sublime Text, I installed babel-sublime to have full support of the Babel syntax!

.editorconfig

The .editorconfig file can be used with your IDE/editor to mantain a consistent coding style. See editorconfig.org for more info. (thanks to @lohek)

Linting

I use eslint with babel-eslint and the react plugin – config in .eslintrc. I also configured Sublime Text with SublimeLinter-eslint.

npm run lint

I use SublimeLinter-scss-lint for linting the Sass files (.scss-lint.yml).

Debugging

The app uses debug to log debug messages. You can enable/disable the logging from Node by setting the DEBUG environment variable before running the server:

# enable logging for isomorphic500 and Fluxible
DEBUG=isomorphic500,Fluxible node index

# disable logging
DEBUG= node index

From the browser, you can enable/disable them by sending this command in the JavaScript console:

debug.enable('isomorphic500')
debug.disable()
// then, refresh!