Skip to main content

Setting Up Your Environment

Prerequisites​

The examples in this documentation assume that you have already set up an MSFS project in the SDK/Dev mode, have an aircraft panel.cfg appropriately created, or in use, and understand how to modify that config file to point at the example HTML avionics instrument.

You will also need Node 12+ and npm installed on your machine, as well as a quality code editor. We recommend Visual Studio Code for this purpose.

Creating a Framework Project​

Create a folder in a convenient location that will house your project. For this tutorial, we will call it my-avionics. After you have create that folder, navigate to it on the command line and create an npm project:

> npm init -y

After this command has finished, you should now have a package.json file in your my-avionics folder.

Installing the Framework Into Your Project​

tip

All our frameworks are now available for installation by npm, so it is no longer necessary to download and build them yourself.

You can install the base avionics framework into your project by running the following:

> npm install @microsoft/msfs-sdk @microsoft/msfs-types --save-dev

Additional packages are available for certain avionics platforms. Those working on Garmin avionics will want to install @microsoft/msfs-garminsdk. Other packages may be available for individual avionics, such as the G3000. See individual system documentation for more on those.

Initializing Your TypeScript Project​

While it is possible to use the framework from plain vanilla Javascript, we highly recommend using TypeScript for development, and all the examples presented will assume that you are using TypeScript as your language of choice. To install TypeScript and initialize your TypeScript project:

> npm install typescript --save-dev
> npx tsc --init

This will create a tsconfig.json that contains the compilation options for TypeScript for this project. We will want to adjust some of the options within this file. Ensure that your tsconfig.json has the following options set:

{
  "compilerOptions": {
    "incremental": true, /* Enables incremental builds */
    "target": "es2017", /* Specifies the ES2017 target, compatible with Coherent GT */
    "module": "es2015", /* Ensures that modules are at least es2015 */
    "strict": true, /* Enables strict type checking, highly recommended but optional */
    "esModuleInterop": true, /* Emits additional JS to work with CommonJS modules */
    "skipLibCheck": true, /* Skip type checking on library .d.ts files */
    "forceConsistentCasingInFileNames": true, /* Ensures correct import casing */
    "outDir": "build", /* Sets the output folder to ./build */
    "moduleResolution": "node", /* Enables compatibility with MSFS SDK bare global imports */
    "jsxFactory": "FSComponent.buildComponent", /* Required for FSComponent framework JSX */
    "jsxFragmentFactory": "FSComponent.Fragment", /* Required for FSComponent framework JSX */
    "jsx": "react" /* Required for FSComponent framework JSX */
  }
}

Installing and Configuring Rollup​

Because the Coherent GT system used by MSFS uses a custom URL scheme (coui://), it can be difficult to use the standard module systems and import syntaxes available. We recommend using a bundling system to bundle your project into a single file, and we will configure Rollup for that purpose here.

To install Rollup along with a few plugins we will use:

> npm install rollup@2 @rollup/plugin-node-resolve @rollup/plugin-typescript rollup-plugin-import-css tslib --save-dev

This will install Rollup itself, as well as the following plugins:

  • plugin-typescript - Allows Rollup to bundle and compile TypeScript in one step, without needing to run tsc manually.
  • plugin-node-resolve - Allows Rollup to resolve packages that were installed via NPM, such as the avionics framework, and bundle that along with your code
  • rollup-plugin-import-css - Allows you to use import declarations in your code (like import './MyComponent.css') that point to CSS, and then bundle all that CSS into a single CSS file

Once everything is installed, create a rollup.config.js file in your project root with the following contents:

import typescript from '@rollup/plugin-typescript';
import resolve from '@rollup/plugin-node-resolve';
import css from 'rollup-plugin-import-css';

export default {
  input: 'MyInstrument.tsx',
  output: {
    dir: 'build',
    format: 'es'
  },
  plugins: [css({ output: 'MyInstrument.css' }), resolve(), typescript()]
}

This configuration imports the plugins that we installed earlier, and then exports a Rollup configuration. The configuration takes in MyInstrument.tsx and will output the bundle into the ./build folder with the Coherent GT/MSFS compatible ES module format. We also configure the CSS plugin to output a bundled MyInstrument.css, which will also appear in the output folder.

Finally, add the following to your package.json file to configure an NPM step that will run your Rollup build:

...
"scripts": {
  "build": "npx rollup -c" //Add this line to the scripts configuration object
},
...