Remix-Composer

remix-composer is a build time microfrontend tool that merges multiple Remix applications into a single unified wrapper application. This simplifies management and deployment while supporting environment-specific configurations for branches and applications.

Installation

Install remix-composer as a development dependency in your wrapping application:

npm install -D remix-composer

Configuration

Create a configuration file named remix-composer.config.json in the root of your project. This file defines the applications to merge and their respective settings.

Example Configuration

{
    "subApplications": [
        {
            "name": "dashboard",
            "repo": "https://github.com/foo/bar.git",
            "envConfig": [
                {
                    "NODE_ENV": "development",
                    "branch": "dev"
                },
                {
                    "NODE_ENV": "qa",
                    "branch": "qa"
                },
                {
                    "NODE_ENV": "production",
                    "branch": "prod"
                }
            ]
        }
    ]
}

Configuration Options

subApplications

An array of objects, each representing a sub-application to merge.

• name (string): The name of the sub-application.
• repo (string): The Git repository URL of the sub-application.
• envConfig (array): Defines environment-specific configurations.
  • NODE_ENV (string): The environment name (e.g., development, qa, production).
  • branch (string): The branch to use for the specified environment.

Notes:

• All configuration options are required.

Usage

Run the tool using the following command:

remix-composer

You can also specify an environment flag to select a specific branch and configuration:

remix-composer --env qa

How It Works

The --env flag maps to the envConfig specified in your configuration file. For example, running remix-composer --env qa will:

• Set NODE_ENV to development
• Use the dev branch as defined in the example configuration.

File Structure After Merging

When remix-composer runs, all subApplications are merged into the wrapper application as follows:

• Routes: Sub-application routes are added under app/routes/<subApplications.name>.<file-name>.tsx.
• Imports: remix-composer analyzes and resolves project-specific imports marked with "@/" (e.g., import Header from "@/components/Header").
  • These components, utilities, or dependencies are copied into subdirectories within the wrapper application, such as app/components/<subApplication.name>/Header.tsx.
  • Import statements are updated to reflect the new locations.
• Dependencies: Sub-application package.json files are analyzed, and their dependencies, peerDependencies, and devDependencies are merged into the wrapper application. If two sub-applications declare the same dependency with different versions, the newest version will be used.

Key Notes:

• Original code in the sub-application repositories remains untouched.
• All modifications occur on copied files inside the parent (wrapper) application.

Key Features

• Environment Mapping: Seamlessly map environments to specific branches using the envConfig option.
• Multi-App Merging: Easily merge multiple Remix applications into one.
• Automatic Import Updates: Resolve and adjust project-specific imports for a unified structure.
• Dependency Resolution: Automatically merge and deduplicate dependencies across sub-applications.
• Non-Intrusive: Sub-application repositories remain unmodified; all changes are scoped to the wrapper application.
• Custom Configuration: Fully customizable via a simple JSON configuration file.

Caveats

THIS PROJECT IS STILL ALPHA

Currently it only merges package.json, routes, components

To Dos:

1. Migrate to React Router v7.x
2. Shared state between subApplications and wrapper application
3. Expand the merge to include: typeDefs, stores, hooks, APIs/Middleware, Contexts etc...

This package is highly opiniated around the project structure and will probably become even more so in later versions. It is designed to only work with a group of applications running on the same React/Remix versions. The purpose is to have invidual siloed projects that can be developed and deployed in isolation but then also deployed via a single unified wrapper application, i.e. you can have a Header component in the wrapper which links to the individual subApplication routes.

Why?

This significantly improves performance and developer experience compared to module federation. If you are building applications as part of a larger application suite. You can work in isolation in lower environments, and then deploy to a single unified application in the upper environments for simpler user experience and end to end testing.

License

This project is licensed under the ISC License.

Copyright 2024 Hassan Mehdi

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.