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.
- Modular design allowing for groups of UI components to be independently developed, tested, and deployed.
- Easy configuration management.
- Server side rendering as a first class citizen.
- Built-in internationalization.
- Built-in dynamic routing.
For a breakdown on these features and an architectural overview, take a look at our overview documentation
Create 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). This will use the
One App Module Generator
to generate a basic One App module.
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-moduleSelect the root module option when asked.
Docker is required for this next step
When the generator has finished:
cd ./[your-module-name]
npm startVisit localhost:3000
Please follow the Getting Started guide for more information.
When you want to work on One App directly or are unable to use One App Runner
export NODE_ENV=development
git clone https://github.com/americanexpress/one-app.git
cd one-app
npm ci --no-optionalWhen you are directly running the One App server locally and would like to load a local Module
At the root of your one-app repo, run:
npm run serve-module <path-to-local-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.
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.
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 One App community can be found on GitHub Discussions, where you can ask questions, voice ideas, and share your projects.
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.