Skip to main content

Migrate to the App Folder Structure

A critical component in Rhapsody's architecture is the idea of an "app". An app is a self-contained slice of Rhapsody that is specific to a domain, is owned by a single team, registers itself with the platform, and is decoupled from other apps in Rhapsody. For more information on Rhapsody's architecture, see the Rhapsody Vision and Architecture doc.

Migrating existing code from the /src directory to individual apps involves two steps: planning the migration, and executing the migration.

Plan the migration​

Moving code into the app structure needs to be well-planned as almost all code requires changes before migrating. Code in the app structure has stricter requirements around removing legacy code and using latest best practices. Exact requirements for migration are defined in the next section. The first step in planning out the migration is to identify the code that needs to migrate. This may seem obvious, but if you are migrating code by route, for example, you will need to track down which directories relate to which routes. The second step is to run the migration CLI helper to generate a report on what must be fixed or refactored to satisfy the migration requirements. Run the following to view usage instructions:

pnpm app-migration

With the report, you and your team can break down the work into more granular units and create the necessary structures (Jira cards, Productboard entries, etc.) to track them.

Migration Requirements​

The following requirements must be satisfied before code can be migrated to an app:

  • No Angular dependencies: Apps must have zero Angular dependencies. React components must not have props passed in from Angular controllers. Code must not inject Angular modules via src/services/ng.
  • No relative imports outside the current app: Apps are meant to be self-contained and decoupled from other parts of the application. Consequently, they are not allowed to relatively import code outside of themselves. For instance, code in apps/accounts is not allowed to reach into src/services or apps/people when importing code. Absolute imports for platform and shared packages (e.g. @rhapsody/auth-context, @shared/requests) are still allowed.
  • All ESLint rules are satisfied: In the src/ directory, we only enforce ESLint rules on lines that have changed. This is not true for code in the apps/, platform/, and shared/ directories. ESLint rules are enforced for an entire file regardless of which individual lines have changed.
  • No legacy Rhythm packages: All legacy Rhythm packages must be removed and replaced with UI Kit equivalents. Legacy Rhythm packages include @rhythm/common, @rhythm/core, @rhythm/banners, @rhythm/react-quest, and @rhythm/date-time-picker.
  • No deprecated or pre-rebrand colors: All CSS-in-JS color names should use the current color names.
  • No icon fonts: All references to Font Awesome (fa and fa-* CSS classes) and the SalesLoft font icon set (sl-icon and sl-* CSS classes) should be removed. Use equivalents from @rhythm/svgs.
  • No reserved top-level providers: Certain top-level React providers are no longer necessary in app code since the platform will ensure they are at the top of the component tree. These top-level providers include ThemeProvider from @rhythm/theme, QueryClientProvider from @rhapsody/query-client, and AppRouter from @rhapsody/routing. NOTE: this is a soft requirement since duplicates in the component tree do not cause an issue and any instances of reserved top-level providers in your code will emit a warning instead of an error.

Any violations of the above requirements need to addressed before migrating code. These requirements are enforced by our linters and cannot be overridden. CI checks will fail if any of these are found in apps directory code.

Executing the migration​

Once your migration is planned, you can begin actually migrating your code.

Filesystem Layout and Folder Structure​

First, familiarize yourself with the filesystem layout and folder structure for apps. All apps live in a top-level /apps directory with each app inside it's own directory. For example, an app for analytics would be in /apps/analytics. While we do not currently enforce how code is organized inside of an app directory, we do have a recommended folder structure that will allow for a consistent developer experience across apps. Assuming . below is the root of an app (e.g. /apps/dialer), we recommend the following folder structure:

.
├── entry.ts           # Entry file to register with the App Registry
└── src                # Directory containing all other app code
    ├── assets         # Static assets (images, etc.) for the app - Optional
    ├── bridge-loaders # Bridge loaders registered with the App Registry
    ├── common         # Code used throughout the app (constants, types, etc.) - Optional
    ├── components     # React components
    └── services       # Vanilla JS/TS business logic (API requests, data transformation, etc.)

If you are creating a new app from scratch, you can use Rhapsody's scaffolding script to generate the above files and directories for you:

pnpm scaffold app

If you are moving code into an existing app, you do not need to run any scripts.

Move the Code and Register It​

Since apps have a different directory structure than what is currently in /src, you will most likely need to reorganize your code when moving it. Decide what needs to go where and move your code over.

tip

Use git mv when moving code to keep its git history intact.

Once that is complete, open the entry.ts file at the root of your app and register relevant parts of your application with the platform. For more information on registering with the platform, see the How To Use the App Registry doc. With your code moved and registered, it's time to migrate dependencies.

Migrate Dependencies​

Rhapsody provides a CLI tool to auto-populate an app's package.json with all the dependencies used in code. Run the following command with your app's base path (where package.json exists) as the first argument:

pnpm migrate-deps apps/<APP_NAME>

This will update your app's package.json, give you a change to confirm the changes, and run pnpm install. Once that step is complete, (re)start Rhapsody's dev server to see your app in action.