One App is a fresh take on web application development. It consists of a Node.js server that serves up a single page app built using React components and makes use of Holocron to allow for code splitting via independently developed, tested, and deployed Holocron Modules.
Our goal is to provide a web application framework for building fast, scalable, secure, and modular experiences. Leave the tooling to us and focus on what matters - delivering performant, maintainable experiences to your users.
While American Express has been using One App in production since 2016, this open source iteration of the framework is in a soft launch state. There will be a full documentation site forthcoming.
Want to get paid for your contributions to one-app?
Send your resume to [email protected]
- Modular design allowing for groups of UI components to be independently developed, tested, and deployed.
- Server side rendering as a first class citizen.
- Easy configuration management.
- Built-in internationalization.
- Built-in dynamic routing.
Build a Module with generator-one-app-module
The easiest way to do this is via npx (comes with npm versions 5.2.0 and above). Run the following command in the directory you want your module to live:
export NODE_ENV=development
npx -p yo -p @americanexpress/generator-one-app-module -- yo @americanexpress/one-app-moduleThis will use the One App Module Generator to generate a basic One App module.
export NODE_ENV=development
git clone https://github.com/americanexpress/one-app.git
cd one-app
npm ci --no-optionalAt the root of your one-app repo, run:
npm run serve-module <local-path-to-generated-module>
# e.g. npm run serve-module ../my-first-moduleThe serve-module command generates a static folder in the one-app root directory, containing a module-map.json and a modules folder with your bundled module code:
one-app/static
├── module-map.json
└── modules
└── my-first-module
└── 1.0.0
├── my-first-module.browser.js
├── my-first-module.browser.js.map
├── my-first-module.legacy.browser.js
├── my-first-module.legacy.browser.js.map
├── my-first-module.node.js
└── my-first-module.node.js.map
Paired with the built-in one-app-dev-cdn library, you're able to utilize the Holocron Module Map while running your entire One App instance locally. No need to deploy and fetch remote assets from a CDN at this step.
Start up One App and declare your new module as the Root Module:
npm start -- --root-module-name=<module-name>
# e.g. npm start -- --root-module-name=my-first-moduleThis starts One App and makes it available at http://localhost:3000/ where you can see it in action!
Open another terminal window, run npm run watch:build in your module's directory and make some edits to the module. One App will pick up these changes and update the module bundles accordingly. When you reload your browser window, One App will be displaying your updated module.
The root module serves as the entry point for one-app to load an application.
| ------ your application ------- |
* one-app -> root-module -> [other modules] |
| ------------------------------- |
It is possible for your application to consist of only the root module, however most application will want to take advantage of code splitting using Holocron and have the root module load other modules. More on this in the Routing section in the API docs.
For a module to act as the root module the only requirements are:
- Returns a React component bundled with one-app-bundler.
- Provides a valid content security policy though the appConfig static.
📘 More Information
- Root Module example: frank-lloyd-root
- App Configuration in your Root Module
- What are Holocron Modules?
- Useful Local Development Commands / Options
Recipes feature our guided tutorials and walkthroughs of building Holocron Modules and running the one-app Server runtime.
Please visit our Recipe Docs.
Our API Docs break down each part of our public APIs for One App and its supporting libraries (e.g. Holocron, one-app-ducks, etc).
Please visit our API Docs.
We welcome Your interest in the American Express Open Source Community on Github. Any Contributor to any Open Source Project managed by the American Express Open Source Community must accept and sign an Agreement indicating agreement to the terms below. Except for the rights granted in this Agreement to American Express and to recipients of software distributed by American Express, You reserve all right, title, and interest, if any, in and to Your Contributions. Please fill out the Agreement.
Please see our CONTRIBUTING.md.
Any contributions made under this project will be governed by the Apache License 2.0.
This project adheres to the American Express Community Guidelines. By participating, you are expected to honor these guidelines.