By default, hot reloading is enabled for the react components tree in accurapp, but if you want to hot-reload also the mobx-state-tree files, your index.js should look like this:

let state = State.create()

function renderApp() {
  ReactDOM.render(
    <MobxProvider state={state}>
      <App/>
    </MobxProvider>,
    document.getElementById('root'),
  )
}

// First render
renderApp()

// Hot module reloading
if (module.hot) {
  // Some component changed, rerender the app
  // and let the react-diffing handle the changes
  module.hot.accept('components/App', () => {
    console.clear()
    renderApp()
  })

  // Store definition changed, recreate a new one from old state and rerender
  module.hot.accept('state', () => {
    state = State.create(getSnapshot(state))
    console.clear()
    renderApp()
  })
}

The first argument to module.hot.accept must be the root component of the app, often the Routes component is used.

You can put them in the src/images folder and require them from the js like this:

import logo from '../images/logo.png'

console.log(logo) // /logo.84287d09.png

function Header() {
  // Import result is the URL of your image
  return <img src={logo} alt="Logo" />
}

or from the CSS (see css-loader for more info):

.Logo {
  background-image: url(~images/logo.png);
}

The advantage is that it creates a hash in the filename to invalidate eventual caching. Another thing is that images that are less than 10,000 bytes are imported as a data URI instead of a path, to reduce the number of requests to the server.

Also you could tell webpack to automatically optimize the images you import with the imagemin-webpack-plugin.

You can put them in the src/fonts folder and require them from the CSS like this (see css-loader for more info):

@font-face {
  font-family: 'Helvetica Neue';
  src: url('~fonts/HelveticaNeue-Thin.ttf') format('truetype');
  font-weight: 200;
}

You usually put the assets you require from the index.html here. Like for example the favicon.

If you need a service worker file just for making the app work offline, use the offline-plugin. An alternative is the workbox-webpack-plugin.

You should normally import stylesheets, images and fonts in JavaScript files using the Module System because this mechanism provides a number of benefits.

The public folder is a useful workaround that gives you access from browsers to a file, outside the Module System. If you put a file into the public folder, it will not be processed by Webpack. Instead it will be copied into the build folder untouched.

Be careful because with this approach files are not post-processed or minified and first of all, if lost, they will cause 404 errors.

For technical in-depth analysis read the create-react-app [documentation].(https://facebook.github.io/create-react-app/docs/using-the-public-folder)

By default you can import svgs as files, like you would do for images:

import logo from '../images/logo.svg'

console.log(logo) // /logo.84287d09.svg

function Header() {
  // Import result is the URL of your svg
  return <img src={logo} alt="Logo" />
}

But if the svg is an icon, and you need to apply some styles to it, you can also import it as a react component, and pass it some className or style props:

import { ReactComponent as PencilIcon } from '../icons/pencil.svg'

// It's like doing
// function PencilIcon(props) {
//   return (
//     <svg viewBox="..." {...props}>
//       ...
//     </svg>
//   )
// }

function Edit() {
  // .db displays the svg as a block, removing the little space
  // underneath that the default inline-block svg has
  //
  // .w1 sets the dimensions, you can also set the dimensions
  // in px using the style attribute
  //
  // .black colors the icon black, like you would do with text
  return <PencilIcon className="db w1 black" />
}

Under the hood, the loader basically wraps the svg file inside a react component, so you can treat it as such.

This strips the svg file from its original styles, because it inherits the style from the color you give it through fill="currentColor". If you want to keep the colors instead, call the svg like this: pencil.colors.svg.

Furthermore it optimizes and minifies the svg using svgo, so it cleans up automatically the ugly and noisy svg that Illustrator exports 🙌.

TypesScript is not enabled by default in accurapp, to bootstrap a project with typescript you will have to run:

npx create-accurapp project-name --typescript

Note: If your project fails to start right after installing, npx may be using a cached version of create-accurapp. Remove previously installed versions with npm uninstall -g create-accurapp

Otherwise, if you have an existing javascript project and want to switch to typescript, you will just have to rename the index.js to index.tsx. On the next yarn start, typescript will be installed as a dependency, a tsconfig.json and a types.d.ts will be created, and you will be able to do your magic in typescript! 🧙‍♂️

Here is how a basic typescript component should look like:

interface Props {}
interface State {}

export class App extends React.Component<Props, State> {
  state = {}

  render() {
    return <div>...</div>
  }
}

See the Typescript JSX guide for more info.

Note: Constant enums and namespaces are not supported.

The easiest way to override a loader is to do it inline, by prefixing the import with a !.

For example:

import csvString from '!raw-loader!../data/some_data.csv'

This will override the default csv-loader for that file.

See the related docs.

Make sure to disable the related eslint rule like this:

{
  "extends": "eslint-config-accurapp",
  "rules": {
    "import/no-webpack-loader-syntax": "off"
  }
}

Accurapp comes with postcss-fuss, a postcss plugin that lets you generate custom functional css classes, in the tachyons way. It's useful if you want to define custom colors, and don't want to write all the classes by hand. And for many other stuff.

For example, this is what you write in your style.css:

@fuss color(tomato, #ff6347);

And this is what the generated css looks like:

.tomato { color: #ff6347 }
.bg-tomato { background-color: #ff6347 }
.b--tomato { border-color: #ff6347 }

There are other preset functions, like color-variants() which outputs both a lighter and darker version of the color, color-states() which outputs the classes in the hover active and focus pseudo-classes. You can even create your own custom modifier function!

More info in the postcss-fuss readme.

Prettier is already configured in the projects scaffolded by accurapp, you just need to install the prettier plugin in your editor of choice and tell it to read the project's configuration.

You should also configure prettier to run on save, it is really useful especially when you paste code from stackoverflow.

First of all, we're sorry for you, IE is an asshole.

You first need to edit the package.json's "browserslist" field, and change not ie 11 to ie 11. If you need to test in local you can also add ie 11 to the development browsers.

You will now have to provide polyfills for the newer apis you're using, for example the fetch polyfill, or the css variables ponyfill. Or you can use react-app-polyfill which is a collection of the most common polyfills.

Also make sure the tools you're using support IE11, for example MobX v5 has no support for IE11.

Now hopefully you will not have any js errors in IE11 (if not, call Dr. Fugaro).

You still have some css fixes to do, for example flexbox behaves weirdly, here are some tips on how to handle this issue.

For simple use-cases you can use greenlet which lets you write javascript functions in the main code and then runs them in a web worker.

Otherwise, you can name your file *.worker.js (or *.worker.ts if you use typescript) and import it normally, accurapp will take care of the rest (using worker-loader under the hood).

For example, this is how you setup a typescript worker:

// src/myawesome.worker.ts

// You can import modules in this worker
import { get } from 'lodash'

declare var self: Worker

// Listen to message from the parent thread
self.addEventListener('message', event => {
  console.log(event)
  // Post data to parent thread
  self.postMessage({ data: 'maronn' })
})

// src/index.tsx

import Worker from './workers/myawesome.worker.ts'

const worker = new Worker()

worker.postMessage({ data: 1000 })
worker.addEventListener('message', event => {
  console.log(event)
})

Since a service worker cannot be imported as a js module, you will have to put your service-worker.js in the public/ folder.

Doing so you will not have any babel or typescript transpilation in the service worker file. However you can still use ES6 since browsers that support service workers also support ES6 out of the box.

After having created the file, you can register it like this:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register(`${process.env.PUBLIC_URL}/service-worker.js`)
}

Using a service worker is tricky, read more about integrating a service-worker in a SPA.

If you want to use more advanced pattern and strategies, check out Workbox, here is its webpack plugin that might make your life easier.

You can use react-helmet to dynamically add html tags to the <head> of a document and react-snap to prerender them statically after the build process is complete. Here's how to configure them.

Install react-helmet and react-snap

yarn add react-helmet react-snap

Add meta tags for each route in the render function

As specified in the react-helmet documentation. E.g.

export default class Home extends React.Component {
  render() {
    return (
      <Helmet>
        <title>Home title</title>

        {/* Google */}
        <meta name="description" content="Home description" />
        <meta name="copyright" content="Client name" />

        {/* Facebook */}
        <meta property="og:title" content="Home title" />
        <meta property="og:type" content="website" />
        <meta property="og:description" content="Home description" />
        <meta property="og:url" content="Home url" />
        <meta property="og:image" content="Home img url" />

        {/* Twitter */}
        <meta name="twitter:image" content="Home img url" />
        <meta name="twitter:title" content="Home title" />
        <meta name="twitter:description" content="Home description" />
        <meta name="twitter:card" content="summary_large_image" />
        <meta name="twitter:site" content="Client Twitter handle" />

        {/* Chrome for Android */}
        <meta name="theme-color" content="Hex value" />
      </Helmet>

      <main className="homePage">
        {/* Homepage content */}
      </main>
    )
  }
}

Please note that some of these meta can be put directly in src/index.html, as they are probably the same for all pages. Specifically, copyright, og:type, twitter:card, twitter:site.

Add react-snap in src/index.js

import { render, hydrate } from 'react-dom'

renderApp()

function renderApp() {
  if (rootElement.hasChildNodes()) {
    hydrate(<App />, rootElement)
  } else {
    render(<App />, rootElement)
  }
}

Add react-snap to package.json

"scripts": {
  // ...
  "postbuild": "react-snap"
},
"reactSnap": {
  "puppeteerArgs": [
    "--no-sandbox"
  ]
}

Note: the puppeteerArgs avoid the build to break on the Bitbucket pipelines.

Add the react-snap config in bitbucket-pipelines.yml

Add it in script, right before git clone --branch="master" ...

- apt-get update; apt-get install -y gettext-base;
- echo 'deb http://dl.google.com/linux/chrome/deb/ stable main' > /etc/apt/sources.list.d/chrome.list
- wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -
- set -x && apt-get update && apt-get install -y xvfb google-chrome-stable
- wget -q -O /usr/bin/xvfb-chrome https://bitbucket.org/atlassian/docker-node-chrome-firefox/raw/ff180e2f16ea8639d4ca4a3abb0017ee23c2836c/scripts/xvfb-chrome
- ln -sf /usr/bin/xvfb-chrome /usr/bin/google-chrome
- chmod 755 /usr/bin/google-chrome

OK, setup done! Now, how do I check if it is working?

Run yarn build. After the build is complete, you will see some folders with an index.html file in them. Also react-snap shows its progress in the terminal right after yarn build task is complete.

Basic troubleshooting: react-snap works properly, but no links are found

You probably forgot to add <a href="{dynamicLink}"> to the page. React-snap renders all pages looking for <a> tags. It then follows the href to render the subsequent pages. If no <a> tags are found, then no links are crawled. This is particularly important, as some routers hide their logic in an onClick event handler, and don't compile your links to actual <a> tags by default (e.g. mobx-state-router).

Basic troubleshooting: I get a weird error for 404 pages

On 404 pages, react-snap requires you to have the string 404 to be part of the <title>, such as

<title>404 - Page not found</title>

In the future, it might be possible to overcome this limitation (for this, follow #91)

Basic troubleshooting: There is unknown code in my built index.html. Is it malicious? How do I remove it?

Most likely, it is one of the third party scripts you included in the bundle. For example, when one includes Google Tag Manager, react-snap executes the script and the result is put into the index.html.

If this is not what you wish, you can avoid react-snap executing that function like this:

const isSnap = navigator.userAgent === 'ReactSnap'
if(!isSnap) {
  // Google Tag Manager IIFE goes here
}

For more info on this, please see userAgent on the react-snap documentation

Further troubleshooting

Please, refer to the documentations for react-helmet and react-snap.

What goes in the <head>?

Please, see @joshbuchea's head repo.

This guide is a good one to follow, and here is a working example of accurapp with electron. Good luck!

Your best bet is to use yarn workspaces. It will solve you a lot of headaches.

This is an example package.json, assuming that your multiple projects are in a subfolder called projects.

{
  "name": "main-project-name",
  "private": true,
  "workspaces": [
    "projects/*"
  ]
}

Yarn workspaces basically puts your dependencies in just one place, at the root.

This approach allows you to require files across projects really easily. It is advised not to make a new project containing only the shared files, but rather choose a project to be the source of thruth, containing every image or UI components.

You are probably loading a very big file.

You can try increasing the max allowed memory for node with the env variable NODE_OPTIONS=--max_old_space_size=4096.

Check out the Setting Env Variables section for info about setting env variables.