nRF Connect SDK Add-on index

This repository includes a collection of index pages for publicly available nRF Connect SDK Add-ons, which are supplementary components that extend the nRF Connect SDK. You can access the index from the nRF Connect for VS Code extension, and browse it on its webpage.

The Add-on index includes files contributed by different organizations.

---

Contributing an Add-on

If your organization has a project that you would like to include in this repository, read the CONTRIBUTING and CONTRIBUTION CHECKLIST for more information.

---

Development of an Add-on index

This and following sections describe how to build and run the nRF Connect SDK Add-on index in the local environment. If you wish to just publish an nRF Connect SDK Add-on, please refer to Contributing an Add-on.

Prerequisites

Node.js 18.18 or later is required (Node.js 22 is used in CI). Older versions — including Node.js 12 — are not supported: npm install and the build scripts depend on modern Node.js and will fail on distributions that ship an outdated runtime. Check your version with:

node --version

To create an Add-on index page of your own, you need to start with cloning this repository and generating a new index JSON file. Use the information in the following sections to make sure that the JSON file is set up correctly.

Generating index.json file

To generate an index.json file, complete the following steps:

1. Open a command terminal in the ncs-app-index root directory.

2. Install the required dependencies:

   npm install
   

3. Generate index.json:

   npm run generate-index-json
   

   The index.json file is created in the resources directory.

4. Copy index.json to ./site/public/.

The index.json is compiled from the files in the ncs-app-index/index directory. To add your Add-on to the index you can either create or modify existing file of your organization in ncs-app-index/index directory.

Adding your organization to the index

To add your organization to the index, create an JSON of your own. The common practice is to name that file after the contributor's organization. The file is required to be located in ncs-app-index/index directory and follow the schema defined in site/src/schema.ts (orgIndexSchema, validTags).

The index schema is defined in site/src/schema.ts. Edit that file to change allowed fields or tags. Running npm install generates a local resources/schema.json (gitignored) for VS Code validation.

The following represents an example of the organization's index file:

{
    "name": "Application maker",
    "description": "A company that makes applications.",
    "apps": [
        {
            "title": "Application #1",
            "name": "application_1",
            "description": "The first application",
            "kind": "sample",
            "tags": ["ble", "dfu"],
            "avatar": "https://link-to-avatar
            "releases": [
                {
                    "date": "2024-08-11T14:37:00Z",
                    "name": "v2.0.1",
                    "tag": "v2.0.1",
                    "sdk": "v2.8.0"
                }
            ],
            "docsUrl": "https://link-to-docs"
        }
    ]
}

For field requirements and allowed tag values, see site/src/schema.ts (orgIndexSchema, validTags).

Serving a local server

Once you have your index.json file, you can set up a local server to test it:

1. Copy index.json to ./site/public/.

2. Go to the site directory.

3. Install the required dependencies:

   npm install
   

4. Build the website locally:

   npm run build
   

   This will create a static build in the /site/out directory.

Verifying website locally

This repository includes a static website that displays the contributed add-ons in a searchable frontend. It's developed using the Next.js React framework, and uses Tailwind for styling.

To verify your application index website locally:

1. Start the website locally:

   npm run dev
   

2. Access the site in the browser by going to localhost:3000/ncs-app-index.

3. Check if the JSON file is available by going to localhost:3000/ncs-app-index/index.json, where index.json is the name of your JSON file.

Website customization

You can customize the local website in the following ways:

• By default, the site runs on port 3000, but this can be overridden by setting the PORT environment variable.

• Add-on data is read at build time. For development purposes, sample data can be imported from sampleData.ts.

Verifying index in the extension

To verify that your add-on index is correctly picked up by the [nRF Connect for Visual Studio Code extension], set the extension to fetch the add-on index from the custom URL:

1. In Visual Studio Code, open settings.json: press Ctrl+Shift+P (Cmd+Shift+P on macOS), search for Preferences: Open Workspace Settings (JSON), and open the workspace settings file for this repository.

2. Add the following line to the file (same base URL as Verifying website locally — include the /ncs-app-index path, not http://localhost:3000 alone):

   "nrf-connect.appIndexUri": "http://localhost:3000/ncs-app-index",
   

3. Save your changes.

4. In the extension's Welcome View, select Create a new application > Browse application index.

Your custom nrf-connect.appIndexUri will be used to list the add-ons in the index.

Query parameters

The add-on index exposes several query parameters for filtering its contents.

Parameter	Type	Description	Example
app	string	Show add-ons that include the app in their name, title, description, or tags.	?app=air+quality
ncs	string	Show add-ons that are compatible with a given nRF Connect SDK version.	?ncs=v2.5.0