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.
👩💻 Hiring 👨💻
Want to get paid for your contributions to one-app?
Send your resume to [email protected]
📖 Table of Contents
✨ Features
- 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
🚀 Quick Start
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.
Clone and Install One App Locally
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-optionalServe local Module's to One App
When 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
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.
Declaring a module as your Root Module and start One App:
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.
📜 Documentation
Community
The One App community can be found on GitHub Discussions, where you can ask questions, voice ideas, and share your projects.
🏆 Contributing
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.
🗝️ License
Any contributions made under this project will be governed by the Apache License 2.0.
🗣️ Code of Conduct
This project adheres to the American Express Community Guidelines. By participating, you are expected to honor these guidelines.