Skip to main content

Project Structure

The App SDK leverages the Nx build system to generate a mono-repo structure for app development. This structure allows developers to create and manage multiple apps and extensions within the same repository. By utilizing the mono-repo approach, developers can easily share code and resources between apps, reducing redundancy and enhancing maintainability. The shared codebase promotes consistency across applications and simplifies collaboration within teams. Therefore our suggested approach is to have one workspace setup and develop all your apps and extensions in it.

Table of Contents​

  1. Overview
  2. Main Directories
  3. Configuration Files In Depth

Overview​

Difference between apps and extensions​

It is important to distinguish between an app and an extension as it might be confusing in the beginning. An "app" serves as a container, bundling one or more "extensions" to create an installable unit. The app handles configuration and metadata such as appearance in the marketplace, installation process, logo, screenshots and descriptive information.

On the other hand, an "extension" is where the main programming efforts are directed to, as it contains the essential application logic and user interface. One or more extensions do, in fact, make up the core functionality of the app.

In simpler terms, think of the app as the external "shell" that brings everything together, while the extensions lie at the very heart of the app, where the functional aspects reside. It's crucial to grasp this distinction early on, but rest assured that it will become clearer as you delve deeper into app development.

Main Directories​

apps​

The apps directory houses the main application projects within the mono-repo. Each app project resides in its own subdirectory. The apps can share code and resources from the libs directory, streamlining the development process and reducing code duplication. The following files are important to understand and are created after generating an app:

  • /[app_name]
    • /src
      • index.ts: Leave it empty as it is an autogenerated file that is not used in our setup.
    • iris-app-manifest.ts: This is a very important file that keeps all your configuration, such as marketplace configurations, activationMode, extensions, etc.
    • package.json: this package.json file's only role is to define the name and version of the application. This is where you bump your version number before pushing a new version of your app.
    • project.json: holds project-specific settings and build configurations and is used by the Nx CLI to understand how to build, test, and serve your application or library. this is where the different targets for the app live. The command "nx run <AppName>:serve" will execute the action described in the serve target in the project.json file, located in the <AppName> folder. Beyond what our guides tell you to do, you likely won't have to look too much into this file to begin with, unless you have a large monorepo and use generic libraries. Reference the Nx documentation for more information.
    • vite.config.ts: configuration file for Vite, the bundler the App SDK uses to build and serve your app. Under normal circumstances you won't touch this file a lot.

libs​

The libs folder should contain all the extensions, tools and helper-functions that you might want to share between apps. When you generate your first extension, you will have a folder structure looking roughly like this:

  • /[feature_name]: This folder contains all extensions, which can be shared between apps. Developers can also create normal NX libraries (not extensions) for tools, helper functions, and other shared code such as React components to share between extensions. We suggest a convention where you bundle all extensions related to an overarching "feature" under a subcategory named after the feature. For example, suppose you want to create a weather-availability feature with an Asset Home Extension that indicates if an asset is safe to use in current weather conditions. To apply this feature at the Fleet level, create a Fleet Extension and apply the same weather-prediction logic to both extensions.
    • /[extension_name]:
      • /src: This folder should house all your code. It is reccomended you bring in your tools, helper functions etc. as dependencies instead of keeping them here.
        • /generated: This folder is automatically generated when you follow our graphql guide.
          • graphql-api.tsx: It houses auto-generated hooks (functions) that call the graphql api for you.
        • /queries: You should create this folder manually and put all your custom graphql queries in it. The hooks above are generated based on the queries you store in this folder
          • [query_name].graphql: This is one of your custom graphql queries.
        • app.spec.tsx: Unit tests for the App component.
        • app.tsx: The entry-point of your custom code logic. Start coding here!
        • index.tsx: The entry-point of your extension. It will initialize the App component above and you shouldn't do any changes here. Your point of interest is app.tsx.
      • extension-manifest.ts: A small configuration file for the extension that controls the type of the extension, the location of the source code and the name of the extension when it is rendered in the UI as a menu item. Depending on the type of extension, differetn configurations will be available. Check the JSDoc of the IrisAppManifest interface for specific explanations.

Configuration Files​

iris-app-manifest.ts​

The most important configuration file in your app. It holds everything the platform needs to know: who can install the app, how it appears in the Marketplace, which APIs it may call, and which extensions it contains.

Every field is documented in the App Manifest reference.

nx.json​

nx.json is the main configuration file for the Nx workspace, containing project-specific settings, cache settings, and task runner configurations. New apps, extensions, and libraries are automatically added here when NX generators are used.

tsconfig.json​

There's rarely any reason to change these. It is a configuration file used by the TypeScript compiler. It contains various settings and options that determine how your TypeScript code should be transpiled into JavaScript, as well as how it should handle type checking and other features. If you haven't worked with Typescript before, familiarize yourself with the official documentation for it.