Awesome

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.

✨ 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-module

Select the root module option when asked.

Docker is required for this next step

When the generator has finished:

cd ./[your-module-name]
npm start

Visit 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-optional

Serve 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-module

The 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-module

This 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.