A Technical Introduction to Flagship

• Flagship Structure
• Notable Packages
  • flagship
  • fsapp
  • fscodestyle
  • fscomponents
  • fsnetwork
  • pirateship
• Dependencies
• Data Sources and Normalization
• fscategory and fsprojectindex

Flagship Structure

Flagship is a mono repo, a single code repository containing the source for multiple separately-published NPM modules. This approach was used because many of the Flagship modules have strong dependencies on each other, potentially making development a challenge if each module had its own repository. We use Lerna to manage the repository. When running Flagship locally, Lerna symlinks Flagship dependencies to their appropriate directories, allowing you to make changes to multiple packages and seeing the result in real time.

Notable Packages

All Flagship packages are located in the packages directory. fscomponents is published to npm as @brandingbrand/fscomponents, fscommerce is published as @brandingbrand/fscommerce, and so on. You can refer to each package for an introduction, but here is an overview of some of the highlights:

flagship

The flagship package (not to be confused with Flagship repo) contains scripts and code for managing the native (iOS and Android) aspects of Flagship React native apps.

The ios and android directories contain bare-bones iOS and Android projects. When a Flagship app is initialized, these folders are copied into the app and the scripts handle things like updating the app name, bundle identifier, and native dependencies.

All Flagship apps require @brandingbrand/flagship as a dependency.

fsapp

The fsapp package contains the core classes and interfaces for Flagship apps. All Flagship apps are an instantiation of fsapp, and pass a configuration object into the fsapp class to handle boilerplate code such as initializing navigation and the Redux store.

All Flagship apps require @brandingbrand/fsapp as a dependency.

fscodestyle

This package contains the linter rules for TypeScript Flagship applications.

fscomponents

This package contains a number of React Native UI components that can be reused across commerce applications. You can view our Component Playground for an interactive listing of the components and their configuration options.

fsnetwork

This package exports an abstracted interface for performing network requests. Currently this package is a wrapper of the Axios library but additional adapters can be added should the need arise. All networking requests should be performed with @brandingbrand/fsnetwork so that the backend is consistent across the app.

pirateship

This is the only package that isn't published to NPM. It's a demo Flagship app that can be used to test changes to Flagship as they're made.

Dependencies

In order to reduce duplicate code and ensure consistency across Flagship apps, we provide default integration with several third party libraries to perform various functions for apps:

React Native Navigation is used for handling navigation. As of this writing Flagship is using version 1 but an upgrade to version 2 is expected in the near future.

React Redux is used for managing global state. While other tools aren't prohibited, fsapp supports a react-redux store out of the box.

Jest is the framework used for writing tests.

React Native Web is used for creating web projects within Flagship using React Native components.

All JS code should be written in TypeScript.

Data Sources and Normalization

Most e-commerce websites use a third party backend for managing their websites to handle things such as product listings, inventory management, and order management. Adobe Commerce Cloud, Salesforce Commerce Cloud, and Shopify are some of the biggest players in this space.

Flagship was designed with the following considerations:

• A large percentage of e-commerce sites use one of these major vendors
• Many e-commerce sites switch vendor platforms on a regular basis

As such, Flagship is designed to abstract away third party APIs from the apps themselves: Flagship apps use a standard data schema, and adapters with normalizers and denormalizers are written to convert data between the Flagship schema and that of each API. If a company switches between vendors that are supported by Flagship, the transition could be as simple as a few lines of code.

Flagship defines its own schema for three major parts of e-commerce apps: commerce, reviews, and analytics.

• The standardized commerce schema is located in fscommerce
• The standardized reviews schema is located in fscommerce (look for ReviewTypes)
• The standardized analytics schema is located in fsengage

API interactions are handled via Data Sources. Data sources should extend from the CommerceDataSource interface, which describes the methods, parameters, and return types that should be implemented. Everything in Flagship that accepts a data source requires the data source to implement this interface.

fscategory and fsprojectindex

These two packages contain turnkey components for rendering category/subcategory and product index (product grid) screens. Simply provide a data source that conforms to the Flagship interface and a few properties (e.g., the current category ID) and these components will handle the API requests and rendering of the screens. Each component is highly customizable.