Creating an Extension

Here’s the mockup of the Restaurants extension that we saw in the Introduction. Through the course of this tutorial, we’ll make the Restaurants extension.

The left app screen lists the restaurants and the right one shows the details of each specific restaurant when you tap on it.


Let’s start building! Initialize the extension with basic information. Following command, shoutem init, will create a folder and bootstrap the extension files.

$ shoutem init restaurants
Enter information about your extension. Press `return` to accept (default) values.
Title: Restaurants
Version: 0.0.1
Description: List of restaurants

Initializing extension:

Extension initialized!

We passed restaurants as an extension name to the shoutem init command. Extension information is stored in extension.json file.


In case you can’t remember the structure of some command, type shoutem -h or shoutem <command> -h where you should replace <command> with one of the CLI commands.

Now lets switch to the extension folder:

$ cd restaurants

Folder Structure

The initialization process will generate the skeleton with folders and files. Our new extension’s structure looks like this:

  ├ app/
  |  ├ node_modules/
  |  ├ extension.js
  |  ├ index.js
  |  └ package.json
  ├ server/
  |  ├ node_modules/
  |  └ package.json
  └ extension.json

Let’s explain the structure:

  • app/: Folder where you keep your mobile app side code (this will be bundled into the app)
  • server/: Folder where you keep your server side code and assets
  • extension.json: File that describes your extension

Specific parts will be explained soon.

In extension.json you can see:

#file: extension.json
  "name": "restaurants",
  "version": "0.0.1",
  "title": "Restaurants",
  "description": "List of restaurants",
  "platform": "1.0.*"

Brief property explanations:

  • name uniquely identifies the extension when combined with your developer name (e.g. tom.restaurants)
  • version is the extension version
  • platform indicates the version of the plaform (versions of React, React Native and other packages available to all extensions by default)
  • title and description are extension descriptors

The extension is now only available on your machine, not to an app on the Builder so lets upload it to Shoutem so you can install it in an app.

$ shoutem push
Uploading `Restaurants` extension to Shoutem...

To test an extension, install it in a Shoutem app. You can create a new app in the Shoutem builder or just pass the flag --new with the name of a new blank app to the installation command:

$ shoutem install --new Restaurants
Extension is installed onto newly created `Restaurants` application.
See it in browser: ``

Follow the link printed by the CLI. Go to the Extensions tab in Shoutem Builder where you’ll see that your extension is installed on the application under the Custom category.

However, when you go to the Screen tab and click on + to add new screen, under Custom category you won’t see your extension.

What’s wrong? Oh right, we should actually add a screen and expose it to the Builder first.