Marketplace App Boilerplate

A boilerplate is a template that is a fitting way to describe distinct repetitive segments of a project to help build projects quickly and efficiently.

They can define any project-level elements or standard methods for one or more projects.

The following guide shows how to use our marketplace boilerplate to build any custom application in Contentstack.

Download the Marketplace App Boilerplate

Before going ahead, download the app boilerplate that we will be using to explain ahead.

Why should you use the Marketplace App Boilerplate?

  • The boilerplate code includes all categories of applications you can create in Contentstack, i.e., custom fields, sidebar widgets, dashboard widgets, and webhooks.
  • Creating any application is prompt since you only need to use the required routes and corresponding components.
  • We build a boilerplate that incorporates all the best practices you can use while building your application in Contentstack.
  • With this template, you can save a considerable amount of development time.
  • The boilerplate also provides the venus components library to make your application correspond with our new Contentstack user interface.

Structure of the Marketplace App Boilerplate

The boilerplate folder structure consists of relative files and references, making it easy to acclimate within your project. This structure also allows the boilerplate to be thoroughly portable between different stacks in Contentstack.

Below is the UI side folder structure of the boilerplate:

ui
├─ .npmrc
├─ README.md
├─ babel.config.js
├─ package-lock.json
├─ package.json
├─ public
│  ├─ favicon.ico
│  └─ index.html
├─ src
│  ├─ common
│  │  ├─ locale
│  │  │  └─ en-us
│  │  │     └─ index.ts
│  │  ├─ types
│  │  │  └─ index.ts
│  │  └─ utils
│  │     └─ index.ts
│  ├─ components
│  │  └─ ErrorBoundary
│  │     └─ index.tsx
│  ├─ containers
│  │  ├─ App
│  │  │  ├─ index.tsx
│  │  │  └─ styles.scss
│  │  ├─ ConfigScreen
│  │  │  ├─ index.tsx
│  │  │  └─ styles.scss
│  │  ├─ CustomField
│  │  │  ├─ index.tsx
│  │  │  └─ styles.scss
│  │  ├─ DashboardWidget
│  │  │  ├─ index.tsx
│  │  │  └─ styles.scss
│  │  └─ SidebarWidget
│  │     ├─ index.tsx
│  │     └─ styles.scss
│  ├─ index.css
│  ├─ index.tsx
│  ├─ react-app-env.d.ts
│  └─ reportWebVitals.ts
└─ tsconfig.json

The build script is available as build.sh in the source code and, when executed, will generate to-deploy/api.zip and to-deploy/ui.zip. To build the UI and API of your app, deploy the to-deploy/ui.zip to AWS S3 and serve it through cloudfront, also, deploy to-deploy/api.zip to AWS Lambda.

Note: If we use the browser-router component in the react app for routing, then in the AWS S3, we must set up a redirect to our index.html for error requests. We are using a HashRouter component instead of a BrowserRouter component to avoid this.

In the HashRouter component, the app route inside the iframe is not accurately identified, and to fix the same, we developed a custom function known as HomeRedirectHandler in ui/src/containers/App/index.tsx.

const App: React.FC = function () {
  return (
    <div className="app">
      <ErrorBoundary>
        <HashRouter>
          {/* If the path is changed here,
              be sure to update the path for corresponding UI location
              in Update App API */
          /* Below list has all the possible UI paths\.
              Keep only the paths that are required for your app and
              remove the remaining paths and their source code also. */}
          <Routes>
            <Route path="/" element={<homeredirecthandler >}="">
            <Route path="/config" element={<configscreen >}="">
            <Route path="/sidebar-widget" element={<sidebarwidget >}="">
            <Route path="/dashboard-widget" element={<dashboardwidget >}="">
            <Route path="/custom-field" element={<customfield >}="">
          </Routes>
        </HashRouter>
      </ErrorBoundary>
    </div>
  );
};</customfield></dashboardwidget></sidebarwidget></configscreen></homeredirecthandler>

For the backend API side, the folder structure is as follows:

api
├─ index.js
├─ package-lock.json
├─ package.json
└─ server.js

Note: We have provided the server.js file to test your application on localhost. This way, you don't need to convert your code to match the lambda function before deploying it to AWS and hence you can run the application on both localhost and AWS saving you time.

Using Marketplace App Boilerplate To Develop Custom Applications

To get started with building applications using the boilerplate, follow the steps given below:

Prerequisites

Install Dependencies

Run the following command to install the necessary packages:

npm install

Creating Project Using The Boilerplate

The boilerplate is only a template to make it easy to build your custom application in Contentstack. You need to revise and add/remove certain specifics to this code as per your application use case.

The following code shows the app manifest you can use to create your custom applications:

{
    "webhook": {
        "signed": true,
        "enabled":true,
        "target_url":"http://localhost:8000", //This is the url where your api server is deployed.

        "channels": [
            "content_types.entries.environments.publish.success",
        ],
        "app_lifecycle_enabled": true,
        "retry_policy": "manual"
    },
    "ui_location": {
        "locations": [
            {
                "type": "cs.cm.stack.custom_field",
                "meta": [
                    {
                        "signed": true,
                        "path": "/custom-field", 
                        "data_type": "json"
                    }
                ]
            },   
            {
                "type": "cs.cm.stack.sidebar",
                "meta": [
                    {
                        "signed": true,
                        "path": "/sidebar-widget", 
                        "data_type": "json"
                    }
                ]
            },
            {
                "type": "cs.cm.stack.dashboard",
                "meta": [
                    {
                        "signed": true,
                        "path": "/dashboard-widget", 
                        "data_type": "json"
                    }
                ]
            },   
            {
                "type": "cs.cm.stack.config",
                "meta": [
                    {
                        "signed": true,
                        "path": "/config"
                    }
                ]
            }
        ],
        "signed": true,
        "base_url": "http://localhost:4000" // This is the url where your ui app is hosted.

    }
}

Note: In above code, a name attribute should be provided in the meta section only if there are more than one objects in the same meta array. Else, we should not give any name attributes. To add more channels within your code, please refer to our Webhook Events documentation.

Your project is now ready!

Uploading The Project To Contentstack

To use your application, you need to upload it to Contentstack. To do so, perform the steps given below:

  1. Log in to your Contentstack account.
  2. On the left-hand-side primary navigation, you will find a new icon for Developer Hub (as shown below). Click on the icon to go to the Developer Hub.
    first_image.png
  3. Click on the + New App button. 
  4. In the New App modal that appears, give a suitable name and description.
    New_Sample_App.png
  5. Click on Create.
  6. On the resulting Basic Information page, upload the icon of your app and Save the changes.
    Basic_Info.png
  7. Next, update the app details via an API call as follows:
    1. While you're on the basic informational page of your app, open “Developer Tools” of your browser (accessible under the “More tools” option of the respective browser), and go to the Network tab.
      imageD.png
    2. Refresh your browser page, and search for user?include_orgs=true (probably the seventh request). Click on it.
      imageE.png
    3. Under the Preview tab of the user?include_orgs=true request’s response, note down the value for user.authtoken. Also, note down the organization’s UID to which your app should be installed, this will be in user.organizations array.
      imageF.png
    4. Open Postman, and pass the following details in your API call:
      • In the URL, pass the App UID that you noted in step 7.c instead of {{APP_UID}}
      • Use the PUT HTTP Method
      • Under Headers, pass the authtoken and organization_uid keys along with the respective values
      • In the Body, pass the name and base_url.

        Note: If some of the UI locations are not required, then you can remove them from the request’s body.locations array.

      URL: https://developerhub-api.contentstack.com/apps/{{APP_UID}}
      
      HTTP Method: PUT
      
      Headers: {
              authtoken: <auth_token_of_contentstack_account>,
              organization_uid: <uid_of_organization>
          }
      
      
      Body(JSON): {
              "name": "<NEW_APP>",
              "target_type": "stack",
                "ui_location": {
                "locations": [
                      {
                          "type": "cs.cm.stack.config",
                          "meta": [
                              {
                                  "signed": true,
                                  "path": "/config"
                              }
                          ]
                      },
                      {
                          "type": "cs.cm.stack.sidebar",
                          "meta": [
                              {
                                  "signed": true,
                                  "path": "/sidebar-widget"
                                  "data_type": "json"
                              }
                          ]
                      },
                      {
                          "type": "cs.cm.stack.dashboard",
                          "meta": [
                              {
                                  "signed": true,
                                  "path": "/dashboard-widget"
                                  "data_type": "json"
                              }
                          ]
                      },
                      {
                          "type": "cs.cm.stack.custom_field",
                          "meta": [
                              {
                                  "signed": true,
                                  "path": "/custom-field",
                                  "data_type": "json"
                              }
                          ]
                      },
                      {
                          "type": "cs.cm.stack.rte",
                          "meta": [
                              {
                                  "signed": true,
                                  "path": "/rte"
                                  "data_type": "json"
                              }
                          ]
                      }
                  ],
                  "signed": true,
                  "base_url": "https://YourWebsite.com"
              }
          }
  8. Next, go to Marketplace and click on the Install App button to install the app in Contentstack.
  9. Select the stack where you want to install the app and click on Install
  10. imageG.png

  11. You will be redirected to the configuration page of the app. Fill in the necessary details to configure your app. 
  12. imageH.png

  13. Click on Open Stack to start using your application within the stack you selected.

Next Step

Next, you can refer to the Get Started with Building Apps using Contentstack’s App SDK guide to start using the Contentstack App SDK in creating your apps.

Was this article helpful?

Thanks for your feedbackSmile-icon

On This Page

^