-
3.1. Install the Node.js dependencies
3.2. Set environment variables
3.3. Update the app name and domains
3.5. Update fonts
-
Hosting your production app on Netlify
8.1. Connect your git repository
8.2. Set the environment variables for your production builds
8.3. Rebuilding and redeploying your web app
This API provides core functionality necessary for most resource-oriented, data-driven applications. It is what you would get if you selected the following for your Molecule:
- Language - TypeScript
- Package manager - NPM
- Renderer - React
- Documentation - TypeDoc
- Testing - Jest
- Logging - Loglevel
- Platforms - Web
- UI - Styled components
- Themes - Light, Dark
- Deployment - Netlify
To add the functionality you need for your own applications, visit Molecule.dev and create your own Molecule. You'll receive a codebase similar to this one with all of the additional functionality you've selected, customized specifically for you.
-
Built with React using
create-react-app
's defaults -
Built for every major platform
- Web browsers
- Desktop
- Mobile
- Tablets
- For other platform support, create your Molecule at Molecule.dev
- iOS
- Android
- Windows
- macOS
- Linux
- Web browsers
-
Written entirely in TypeScript
- Strongly typed
- Clarity of interfaces and intent
- Code auto-completion
- Prevent bugs/mistakes
- Great tooling
-
Thorough code documentation generated by TypeDoc
Want to see the generated docs for yourself? Clone this repository and run
npm install
. -
Code linting with ESLint
- Minimal restrictions while ensuring clean code
-
Unit tests with Jest
- Tests written in TypeScript
-
Logging with
loglevel
-
Custom fonts
- Defaults to Arimo
- Quickly swap with your own
-
Images
- Generate all at once
- App icons
- Favicon
- Logos
- Generate all at once
-
- Automatically generated
- Helps guard against cross-site scripting attacks
- Production builds are automatically updated with sha256 hashes for known inline scripts
-
- Works offline
- Manifest
- Service Workers
-
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)
- 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
, andJSONArray
- Useful when specifying JSON
process.env.*
- A few convenient globals
-
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
- JWT Authorization
- CRUD (create, read, update, delete, query)
- "Things" example resource
- Tests
- Client as an
-
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-browserdatetime
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 currenttheme
- Textarea - A styled
textarea
element - Tests
- Button - A styled
-
Extremely useful React hooks
useAsyncExtendedState
- Same assetState
but with an additional convenientextendState
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 anyPromise
status
- Pending, resolved, or rejectedpromise
- ThePromise
instance itselfvalue
- The resolved valueerror
- The caught errorcancel
- Cancels the promisereset
- Resets the state
- Tests
-
Utilities
- Get human readable error messages
- Get human readable times (how long ago)
- Tests
-
Themes
- Light
- Dark
- Automatically selected by user's OS preference
-
Core application components
- Routes rendered using
react-router
- Fixed header
- Logo
- Theme toggler
- Version update indicator (with button) as a fixed footer
- Tests
- Routes rendered using
-
Layout components
- Default
- Hello (World)
- Default
-
Store component for shared application state as a composition of React hooks
useUser
- A hook which returns the current user (if logged in) and methods to set or extend the user stateuseTheme
- A hook which returns the current theme and a method to set the theme by keyuseVersion
- A hook which returns an object describing the current and potentially new version state and a method to update the service worker, if applicableuseNotifications
- A hook which returns the state of the device/browser's push notifications with methods to enable or disable themusePlans
- A hook which returns available plans and a method to update the user's plan; greatly simplifies cross-platform plan changes and purchaseslocalState
- Saves/retrieves the state of some resource to/fromlocalStorage
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:
- Node.js (version 16 or greater)
The following are recommended:
-
Visual Studio Code - Comes with IntelliSense for modern JavaScript and TypeScript by default, plus automatic linting with a little extra setup.
-
ESLint Extension for VSCode - See the ESLint Setup section below for a step-by-step guide to installation and configuration.
-
Git - Included with OSX, Linux, and VSCode.
After installing Node, navigate to this directory in your terminal and run npm install
to install the app's dependencies. After installation, .env
and .env-cmdrc.js
files with example values will be automatically created, which you should update for your project and environment(s). Documentation will also be automatically generated and opened in your browser where you'll 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.
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.js
. See src/types/process.env.d.ts
for all of the environment variables' type definitions and examples.
Update the .env
and .env-cmdrc.js
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.
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 the word "molecule" 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.
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:
-
Open your logo in Inkscape.
-
Select "File -> Save As..."
-
Select "Optimized SVG" next to "Save as type".
-
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.
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:
-
Copy your font files to your app within the
public/fonts
directory. -
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.
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!
Code linting is a great way to keep your code consistently clean and readable, which helps prevent silly mistakes.
-
Install the ESLint extension within VSCode by opening
File (or "Code" on Mac) -> Preferences -> Extensions
, searching for "ESLint", and clicking the "Install" button. -
Open
File (or "Code" on Mac) -> Preferences -> Settings
, then click the settings icon in the upper right to open your VSCode usersettings.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": [ "javascript", "typescript", "javascriptreact", "typescriptreact" ] }
-
Create a
.vscode/tasks.json
file at the root of themolecule-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.
-
npm install
Installs the necessary dependencies for the app.
-
npm run write-dotenv-files
Writes the default
.env
and.env-cmdrc.js
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 thebuild
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.
-
@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.js
. -
eslint
- Code linter. Helps ensure high quality code. -
eslint-plugin-react-hooks
- Linting for React hooks. -
loglevel
- Minimal logging library which helps with quickly switching between various levels of logging. -
polished
- Create and mix colors. -
quill
- Rich text editor. -
react
- Usingcreate-react-app
's defaults. -
react-dom
- Renders React to the DOM. -
react-router-dom
- Renders layouts depending on the route. -
react-scripts
- Scripts included bycreate-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. -
styled-components
- Style React components with CSS. -
typescript
- Necessary for TypeScript support. -
web-vitals
- Included bycreate-react-app
for measuring performance. -
workbox-*
- Included bycreate-react-app
for service workers. -
axios-mock-adapter
- Utility for mockingaxios
requests when testing. -
http-server
- Serves the production app (possibly locally), if necessary. -
icon-gen
- Generates the favicon. -
if-env
- Used for preventingpostinstall
scripts from running whenCI=true
orNODE_ENV=production
. -
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.
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 your 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.
The app is primarily separated into API
, UI
, and App
component directories, plus common hooks
and utilities
directories, and a themes
directory. 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.
Next, check out the App
documentation for a more in-depth look at the internals and how to add your own resources, routes, and functionality.
This section assumes you have a git repository for your app on either GitHub, GitLab, BitBucket, or another git provider supported by Netlify.
-
Log into Netlify (or sign up).
-
Click the New site from Git button.
-
Connect your git provider and choose your app's repository.
-
The default settings should work, so you should be able to immediately deploy the site.
There are just a few environment variables you should set.
-
Open the "Site settings" tab in Netlify.
-
Go to the "Environment" section under "Build & Deploy".
-
Click the "Edit variables" button and add the following:
-
NODE_ENV=production
-
NODE_VERSION=16
-
GENERATE_SOURCEMAP=false
-
REACT_APP_API_ORIGIN=https://your-app-api.herokuapp.com
- Use the same value you used for your API'sAPI_ORIGIN
environment variable. Also make sure this is set in theproduction
section of{your-app}/.env-cmdrc.js
.
-
Your app will be automatically rebuilt and redeployed whenever you push a change to the master/main branch of your git repository. You can manually redeploy at any time by opening the "Deploys" tab selecting "Deploy site" using the "Trigger deploy" button on the right.
After your app has rebuilt and redeployed (published), you should now be ready to try it out with your production API!
Netlify gives you a unique random URL as a Netlify subdomain for your app, but you'll probably want to use your own official domain.
-
Open the "Domain management" section of the "Site settings" tab for your app in Netlify.
-
Click the "Add custom domain" button under the "Custom domains" section.
-
Enter your app's domain and click "Verify".
If you already own the domain, you will need to follow Netlify's instructions to verify your domain. Or if it's an unregistered domain, you can register it through Netlify.
See Netlify's Custom domains documentation for more information on adding your domain.
It is recommended that you use Netlify's DNS, as it's easy to use and nice to manage it all in one place. It also greatly simplifies the process of adding SSL (HTTPS) to your web app.
After you've added your domain, scroll down to the "HTTPS" section of the "Domain management" page and ensure that SSL is enabled. If you've recently switched to Netlify's DNS, it could take some time for the changes to propagate before you're able to provision a TLS certificate, but from experience, it usually takes less than an hour.
See Netlify's HTTPS documentation for more information on enabling (and troubleshooting) SSL.
Note: You may need to update your API's environment variables to match your domain if it's different than what you originally set on Heroku. You'll want to ensure the
APP_DOMAIN
andAPP_ORIGIN
environment variables are correct, otherwise the CORS configuration will not allow requests to be made from your web app.
If you're using a different DNS for your domain, you can skip this section. Refer to your domain's DNS provider's documentation.
For SSL support on Heroku, you'll need to upgrade to a paid dyno.
To upgrade your dyno and enable SSL for your API:
-
Open the "Resources" tab of your app in Heroku.
-
Click the "Change Dyno Type" button at the top.
-
Choose your dyno type. "Hobby" is probably more than sufficient if you're just starting out.
-
Heroku's "Automatic Certificate Management" should now be enabled, by default.
To add your API's custom subdomain:
-
Open the "Settings" tab for your app in Heroku.
-
Scroll down to the "Domains" section and click the "Add domain" button.
-
Enter your desired API subdomain - e.g.,
api.your-app.com
. -
Copy the "DNS Target" value. You'll add this to Netlify.
To add your subdomain to Netlify's DNS:
-
Open the "Domains" tab of your Netlify dashboard.
-
Click your domain.
-
Click the "Add new record" button under "DNS records".
-
Choose the "CNAME" record type.
-
If your desired subdomain is
api.your-app.com
, enterapi
for the name. -
Paste the "DNS Target" from Heroku as the value.
-
Click the "Save" button.
Note: You may need to update both your app's and API's environment variables to match your domain if it's different than what you originally set. On the API side (in Heroku), you'll want to ensure the
API_ORIGIN
is correct. On the app side (in Netlify), you'll want to ensure theREACT_APP_API_ORIGIN
is correct.