• Public
  • Public/Protected
  • All

Molecule App


This app provides core functionality necessary for most user-oriented, data-driven applications:

  • Built with React using create-react-app's defaults

  • Built for web browsers

  • Written entirely in TypeScript

    • Strongly typed
    • Clarity of interfaces and intent
    • Code auto-completion
    • Prevent bugs/mistakes
    • Great tooling
  • Code linting with ESLint

    • Minimal restrictions while ensuring clean code
  • Unit tests with Jest

    • Tests written in TypeScript
  • Thorough code documentation generated by TypeDoc

  • Logging with loglevel

  • Custom fonts

    • Defaults to Arimo
    • Quickly swap with your own
  • Images

    • Generate all at once
      • App icons
      • Favicon
      • Logos
      • Splash screens
  • Content Security Policy (CSP)

    • Automatically generated
    • Helps guard against cross-site scripting attacks
    • Production builds are automatically updated with sha256 hashes for known inline scripts
  • Progressive Web App (PWA)

  • Preliminary search engine support

    • robots.txt
    • sitemap.xml
  • Prerequisites for app store submissions

    • Basic privacy policy (both in app and as a static web page)
    • Basic terms of service (both in app and as a static web page)
  • Scripts

    • Image generator (logos, icons, splash screens)
    • Generate version.json for web updates
    • Generate environment variable file templates
  • Environment variables

    • Full list of defaults written to disk (git ignored)
    • Extendable sets of variables for common environments written to disk (git ignored)
    • process.env.* type definitions with examples
  • Additional type definitions

    • A few convenient globals
      • JSONValue, JSONObject, and JSONArray - Useful when specifying JSON
    • process.env.*
  • API modules

    • Client as an axios instance
    • Seamless authorization handlers
      • Automatic authorization header storage
      • Automatic authorization renewal
      • Automatic authorization expiration
      • Requires an additional cookie in web browsers for increased security
    • RESTful resources
  • User interface (UI) components built with styled-components

    • Button - A styled button element
    • Center - A styled div using flex box CSS to center its contents both horizonally and vertically
    • Combo - Looks like a select menu, but can type into it like it's an input
    • Error - Accepts an Error instance as children, displayed only if there is an error
    • Form - A wrapper around the native form element with some helpful additions
    • Header - A styled header element
    • Iframe - A styled iframe element which attempts to adjust its height depending on its contents
    • Input - A styled input element (plus consistent cross-browser datetime support)
    • Modal - A custom modal component with the option to position it either center, left, or right; includes an optional close button and/or underlay
    • RTE - A custom rich text editor using Quill, similar in function to the native textarea element
    • Select - A styled select element, normalized to look the same for every major browser
    • Spinner - A spinning icon to indicate loading/pending state
    • StatusIcon - An icon to represent the state of some promise, designed to be paired with the usePromise hook
    • Text - A styled span element to quickly color some text using the current theme
    • Textarea - A styled textarea element
    • Tests
  • Extremely useful React hooks

    • useAsyncExtendedState - Same as setState but with an additional convenient extendState function and the ability to accept promises
      • State can be updated asynchronously, when the promise resolves or rejects
    • usePromise - Manage and render the state of any Promise
      • status - Pending, resolved, or rejected
      • promise - The Promise instance itself
      • value - The resolved value
      • error - The caught error
      • cancel - Cancels the promise
      • reset - Resets the state
    • Tests
  • Utilities

    • Get human readable error messages
    • Get human readable times (how long ago)
    • Convert objects to query strings
    • Open external links in system browser
    • Tests
  • Themes

    • Dark
    • Light
    • Automatically selected by user's OS preference
  • Core application components

    • Routes rendered using react-router
    • Header
      • Logo
      • Theme toggler
    • Version update indicator with update button
    • Tests
  • Layout components

    • Default
      • Hello (World)
  • Store component for shared application state as a composition of React hooks

    • useTheme - A hook which returns the current theme and a method to set the theme by key
    • useVersion - A hook which returns an object describing the current and potentially new version state and a method to update the service worker, if applicable
    • localState - Saves/retrieves the state of some resource to/from localStorage

The app's codebase is opinionated but adaptable to nearly any architecture/design pattern of choice.

Every module is either a pure function (possibly asynchronous), a plain object, or a composition of both, with every function signature and object interface defined using TypeScript.

The app follows a top-down approach designed to be as simple and easy to follow as possible, where application state is rendered, beginning with the route, as a composition of pure function components using either shared state or internal state managed by hooks. Most API functionality is achieved using CRUD (create, read, update, delete, query) abstractions plus utility functions.

Extensive test coverage and separation of concerns make it easy to update and maintain the app while ensuring that it always works as expected.

Modules are thoroughly documented and organized logically and predictably, with exports structured to work nicely with TypeDoc to help you naturally keep your app documentation up to date with less effort.


You will need:

The following are recommended:

First steps

Install the Node.js dependencies

After installing Node, navigate to this directory in your terminal and run npm install to install the app's dependencies. This will also automatically create .env and .env-cmdrc.json files with example values which you should update for your project and environment(s).

Set environment variables

The full list of environment variables specific to the app can be found within the .env file. For all of the various builds, the values in .env are used as defaults, and we use env-cmd to extend these variables per configuration specified within .env-cmdrc.json. See src/types/process.env.d.ts for the app's environment variables' type definitions and examples, and other modules will extend process.env with definitions as needed.

Update the .env and .env-cmdrc.json files with any known values.

Any environment variables beginning with REACT_APP will be included in your application bundle, visible to the public. Your app's environment variables should not include any private keys or credentials.

Update the app name and domains

The app is initially branded as "Molecule". You should change this to match your app.

To quickly update the app's branding, use an IDE (e.g., VSCode) to find all instances of "molecule", "your-api", "your-app", and "Your App" within your app's project directory and replace each instance with your app's name, domain(s), email address(es), etc. It's probably a good idea to review each instance one by one.

Update logos and icons

It's easiest to start with an SVG (vector) image for your logo. If you do not already have a logo, you can find many premade free and open source vector images on the web.

Inkscape is recommended for editing vector images and saving them in an optimized format compatible with React. To overwrite the Logo.svg file included with Molecule in a compatible format:

  1. Open your logo in Inkscape.

  2. Select "File -> Save As..."

  3. Select "Optimized SVG" next to "Save as type".

  4. Overwrite {your-app}/src/App/Logo.svg.

It's also probably a good idea to save a copy using the Inkscape format for future editing, like we've done with {your-app}/src/App/Logo.inkscape.svg.

To generate your logos/icons and splash images, after replacing {your-app}/src/App/Logo.svg with your vector image (using a transparent background), run the following in the terminal within your app's root directory:

npm run generate-images

This generates all of the images necessary (based on your SVG logo) for the web and mobile apps. Feel free to improve and replace the generated images as desired.

Update fonts

Molecule comes with Arimo, a sans serif font metrically compatible with the widely used Arial font.

To replace Arimo with your own choice of font:

  1. Copy your font files to your app within the public/fonts directory.

  2. Update public/index.html and replace all instances of "Arimo" within the @font-face declaration with the your font's sources. It may require some customization depending on your particular font and how you intend to use it.

Update Privacy Policy and Terms of Service

Molecule comes with a very generic Privacy Policy and Terms of Service so you have something to start from, but you will probably need to update them depending on your requirements. They exist in two separate locations.

So that you can link to them from app stores via e.g., https://app.your-app.com/privacy-policy.html:

  • {your-app}/public/privacy-policy.html
  • {your-app}/public/terms-of-service.html

So that users can view them directly within the app:

  • {your-app}/src/App/PrivacyPolicy.tsx
  • {your-app}/src/App/TermsOfService.tsx

You should now be ready to start building your app!

Enable code linting for VSCode (optional)

Code linting is a great way to keep your code consistently clean and readable, which helps prevent silly mistakes.

  1. Install the ESLint extension within VSCode by opening File (or "Code" on Mac) -> Preferences -> Extensions, searching for "ESLint", and clicking the "Install" button.

  2. Open File (or "Code" on Mac) -> Preferences -> Settings, then click the settings icon in the upper right to open your VSCode user settings.json file. Add the following settings:

    "eslint.alwaysShowStatus": true,
    "javascript.format.enable": false,
    "typescript.format.enable": false,
    "eslint.format.enable": true,
    "eslint.lintTask.enable": true,
    "eslint.validate": [
  3. Create a .vscode/tasks.json file at the root of the molecule-app project directory if it does not already exist and add the following task:

    "version": "2.0.0",
    "tasks": [{
    "label": "ESLint",
    "type": "shell",
    "problemMatcher": "$eslint-stylish",
    "command": "npm run lint",
    "windows": {
    "command": "npm run lint"

You should now have linting enabled within VSCode as you develop your app. You can view any problems by selecting the View -> Problems menu.

For more information on customizing your ESLint configuration, visit ESLint.org.

Available scripts

  • npm install

    Installs the necessary dependencies for the app.

  • npm run write-dotenv-files

    Writes the default .env and .env-cmdrc.json files to disk. This is run automatically after installation and you may want to set any variables you already have values for.

  • npm run generate-images

    You can replace src/App/Logo.svg with your own logo and run this command to generate icons and splash images for every platform.

  • npm run lint

    Checks every JavaScript and TypeScript file within the project directory and returns warnings and/or errors for any line of code which doesn't meet our standards.

  • npm run lint-autofix

    Automatically fixes all auto-fixable code based on our linting rules.

  • npm test

    Launches the test runner in the interactive watch mode.

    See the section about running tests for more information.

  • npm run docs

    Uses TypeDoc to generate documentation from comments throughout the codebase. Open docs/index.html to view the documentation.

  • npm start

    Runs the app in the development mode with hot reloading enabled.

    Open http://localhost:3000 to view it in the browser.

    You will also see any lint errors in the console.

  • npm run server

    Serves the production app (possibly locally), if necessary. Serves a production build on port 3333, proxying API requests to localhost, port 4000. Useful for testing production builds locally.

  • npm run snapshot-html

    Uses react-snap to snapshot the initially rendered HTML to give web users something to see other than a blank page before they've downloaded the application JavaScript.

  • npm run build

    Builds the app for production to the build folder, optimized for best performance with minification and hashed filenames.

    Also writes version.json to the build folder and snapshots the HTML.

  • npm run eject

    Note: this is a one-way operation. Once you eject, you can’t go back!

    If you aren’t satisfied with the build tool and configuration choices, you can eject at any time. This command will remove the single build dependency from your project.

    Instead, it will copy all the configuration files and the transitive dependencies (Webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except eject will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.

    You don’t have to ever use eject. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.

Dependencies explained

  • @primer/octicons-react - Open source SVG icons by GitHub.

  • @testing-library/* - Utilities for testing React components and hooks.

  • @types/* - Type definitions for popular libraries. See DefinitelyTyped for more information.

  • axios - Handles API requests.

  • env-cmd - Loads sets of environment variables via .env-cmdrc.json.

  • eslint - Code linter. Helps ensure structured code.

  • if-env - Used for preventing postinstall scripts from running when CI=true or NODE_ENV=production.

  • loglevel - Minimal logging library which helps with quickly switching between various levels of logging.

  • polished - Create and mix colors.

  • quill - Rich text editor.

  • react - Using create-react-app's defaults.

  • react-dom - Renders React to the DOM.

  • react-router-dom - Renders layouts depending on the route.

  • react-scripts - Scripts included by create-react-app for managing the React app.

  • react-snap - Snapshots the initially rendered HTML to give web users something to see other than a blank page before they've downloaded the application JavaScript.

  • react-swipeable - Used for detecting when the user overscrolls (swipes downward beyond the top of the page) so that we can possibly fetch new data.

  • styled-components - Style React components with CSS.

  • typescript - Necessary for TypeScript support.

  • web-vitals - Included by create-react-app for measuring performance.

  • axios-mock-adapter - Utility for mocking axios requests when testing.

  • http-server - Serves the production app (possibly locally), if necessary.

  • icon-gen - Generates the favicon.

  • open-cli - Opens the docs after generation.

  • sharp - Used for generating the icons and splash screens of various sizes based on the SVG logo.

  • typedoc - Generates documentation from comments throughout the codebase.

Documenting your app

If you haven't already, run npm run docs to generate the app documentation.

You should be greeted with this same README plus navigation on the right. This navigation structure matches the project folder structure, based on each module's exports.

If the documentation did not automatically open for you, you can find it at {your-app}/docs/index.html.

For example, click the documentation's API navigation link and you'll see that it expands to show the API module's description and exports: resource, authorization, and client. Take a look at src/API/index.ts and you'll see the same comments and exports.

To create documentation like this as you build your app, include comments and exports using the same structure and run npm run docs again to regenerate your documentation. There are formatting rules which you'll need to follow to generate the documentation the way you want, like including the @module tagged comment at the very top of modules and ensuring there are no blank lines between certain comments and function/object definitions. Visit TypeDoc.org to learn more about how to write documentation alongside your code.

Building your app

The app is primarily separated into API, UI, and App component directories, plus a themes directory and common hooks and utilities directories. Sets of type definitions usually exist as a file or directory alongside the logical grouping of modules/components.

If you would rather use a different architecture, the existing code is designed to be adaptable. Concerns are as separated as possible while using pure, tested functions.

Hosting your production app

Set the environment variables for your production builds

When building your application, set the following environment variables:

  • NODE_ENV=production



  • REACT_APP_URL_SCHEME=com.your-app.app

  • REACT_APP_API_ORIGIN=https://api.your-app.com - Use the same value you used for your API's API_ORIGIN environment variable. Also make sure this is set in the production section of {your-app}/.env-cmdrc.json.

  • REACT_APP_WEB_ORIGIN=https://app.your-app.com

You'll set additional environment variables as needed when following the instructions for setting up features specific to your Molecule.

Generated using TypeDoc