@contentful/app-scripts

@contentful/app-scripts

This project makes easy to perform some recurrent operations in Contentful's App Framework.

📥 Installation

Locally:

npm i --save @contentful/app-scripts

Globally:

npm i -g @contentful/app-scripts

⚙️ Usage

💻 CLI

When installed

$ contentful-app-scripts create-app-definition

Otherwise

$ npx --no-install @contentful/app-scripts create-app-definition

👨‍💻 Programmatic

// my-script.js

const { createAppDefinition } = require('@contentful/app-scripts')
const { myCustomLogic } = require('./my-custom-logic')

(async function main() {
  myCustomLogic();

  await createAppDefinition.interactive()
})()

📜 API

Scripts exported from this module will all be in the following shape

interface Script<Result, Options> {
  // query the user or local cache for required information
  interactive: () => Result;
  // run by automation (`--ci` flag), they would need all the information upfront
  nonInteractive: (...options: Options) => Result;
}

:warning: Please note

Both interactive and nonInteractive version of the same script is meant to return the same result.

Create App Definition

Allows creating a new AppDefinition provided a Content Management Token (more details here).

It only runs in interactive mode.

Example

$ npx --no-install @contentful/app-scripts create-app-definition

Upload a bundle to an App Definition

Allows you to upload a build directory and create a new AppBundle that is bound to an AppDefinition. It runs in interactive or non-interactive mode

Note: The command will automatically activate the bundle. To skip the activation you can pass the --skip-activation argument in interactive and non-interactive mode and then manually activate it

Interactive mode:

In the interactive mode, the CLI will ask for all required options

Example

$ npx --no-install @contentful/app-scripts upload

Non-interactive mode:

When passing the --ci argument the command will fail when the required variables are not set as arguments.

Example

$ npx --no-install @contentful/app-scripts upload --ci \
    --bundle-dir ./built \
    --organization-id some-org-id \
    --definition-id some-app-def-id \
    --token $MY_CONTENTFUL_PAT

Options:

Argument	Description
--bundle-dir	The directory of your build folder (e.g.: ./build)
--organization-id	The ID of your organisation
--definition-id	The ID of the app to which to add the bundle
--token	A personal access token
--skip-activation	(optional) Boolean flag to skip the automatic activation of the AppBundle
--comment	(optional) A comment which will be associated with the created AppBundle. Can be used to differentiate bundles.

Note: You can also pass all arguments in interactive mode to skip being asked for it.

Activate an AppBundle

Allows you to activate an AppBundle for an AppDefinition. When activated the app will serve the newly activated AppBundle.

Interactive mode:

In the interactive mode, the CLI will ask for all required options

Example

$ npx --no-install @contentful/app-scripts activate

Non-interactive mode:

When passing the --ci argument adding all variables as arguments is required

Example

$ npx --no-install @contentful/app-scripts activate --ci \
    --bundle-id some-bundle-id \
    --organization-id some-org-id \
    --definition-id some-app-def-id \
    --token $MY_CONTENTFUL_PAT

Options:

Argument	Description
--bundle-id	The ID of the AppBundle you want to activate
--organization-id	The ID of your organisation
--definition-id	The ID of the app to which to add the bundle
--token	A personal access token

Note: You can also pass all arguments in interactive mode to skip being asked for it.

Open Settings of an AppDefinition

It opens the settings in the contentful web app so that you can use the UI to change the settings of an AppDefinition.

Example

$ npx --no-install @contentful/app-scripts open-settings --definition-id some-definition-id

You can also execute this command without the argument if the environment variable (CONTENTFUL_APP_DEF_ID) has been set.

Example

$ CONTENTFUL_APP_DEF_ID=some-definition-id npx --no-install @contentful/app-scripts open-settings

Clean up bundles

Allows you to clean the list of previous bundles. It fetches the list and deletes all bundles except the 50 newest ones. You can adjust the amount you want to keep by passing --keep <amount> to the argument, if not passed, the default is 50.

Interactive mode:

In the interactive mode, the CLI will ask for all required options

Example

$ npx --no-install @contentful/app-scripts bundle-cleanup

You can also execute this command without the argument if the environment variable (CONTENTFUL_APP_DEF_ID) and (CONTENTFUL_ORG_ID) has been set.

Non-interactive mode:

When passing the --ci argument adding all variables as arguments is required

Example

$ npx --no-install @contentful/app-scripts bundle-cleanup --ci \
    --organization-id some-org-id \
    --definition-id some-app-def-id \
    --token $MY_CONTENTFUL_PAT
    --keep 30

Options:

Argument	Description
--bundle-id	The ID of the AppBundle you want to activate
--organization-id	The ID of your organisation
--definition-id	The ID of the app to which to add the bundle
--keep	Optional, the amount of bundles to keep

Note: You can also pass all arguments in interactive mode to skip being asked for it.