@graphcms/management

@graphcms/management

Programmatically manage GraphCMS project schema via migrations.

Join us on Slack • Login to GraphCMS • @GraphCMS

Quickstart

const { newMigration, FieldType } = require("@graphcms/management");

const migration = newMigration({ endpoint: "...", authToken: "..." });

const author = migration.createModel({
  apiId: "Author",
  apiIdPlural: "Authors",
  displayName: "Author",
});

author.addSimpleField({
  apiId: "firstName",
  displayName: "First Name",
  type: FieldType.String,
});
author.addSimpleField({
  apiId: "lastName",
  displayName: "Last Name",
  type: FieldType.String,
});

migration.run();

Install

npm install @graphcms/management --save-dev

Usage

Changes to your schema starts with a migration.

New Migration

A migration is scoped to an environment. To create a migration, the following parameters are required.

• Authentication Token authToken.

  Can be retrieved from Settings > API Access on https://app.graphcms.com

• Environment URL endpoint.

  Can be retrieved from Settings > Environments on https://app.graphcms.com

• Migration Name name [optional].

  Every migration has a unique name. If unspecified, a name would be generated and will be part of the response of a successful migration.

  Subsequent migrations with same name will fail.

const { newMigration } = require("@graphcms/management");

const migration = newMigration({
  authToken,
  endpoint,
  name, // optional
});

Running a Migration

The run method runs the migration.

By default, migrations run in the background. Passing an optional boolean argument configures the migration to run in the foreground.

const foreground = true;

const result = migration.run(foreground);

if (result.errors) {
  console.log(result.errors);
} else {
  console.log(result.name);
}

Dry Run a Migration

A migration can be dry run to preview what changes would be applied.

const changes = migration.dryRun();

console.log(changes);

Updating an Entity

To update properties, specify the properties to be updated. All ommitted properties remain unmodified.

As a special case, apiId is a requirement because all entities are uniquely indentified by apiId.

To update the apiId, specify newApiId.

Locales

GraphCMS boasts a flexible localization API that you can use to publish content for all or specific locales in your project.

Create a Locale

To create a locale

migration.createLocale({
  apiId,
  displayName,
  description,
});

Update a Locale

To update a locale

migration.updateLocale({
  apiId,
  ... // properties to update
});

Delete a Locale

To delete a locale

migration.deleteLocale(apiId);

Stages

You can create your own content stages, and query content from these stages, as well as publish to.

Create a Stage

To create a stage

migration.createStage({
  apiId,
  displayName,
  description,
  isDefault,
  allowQueries,
  color,
});

Update a Stage

To update a stage

migration.updateStage({
  apiId,
  ... // properties to update
});

Delete a Stage

To delete a Stage

migration.deleteStage(apiId);

Enumerations

Enums values can only contain alphanumeric characters, and underscores.

Create a Enumeration

Create an enumeration with values.

const colors = migration.createEnumeration({
  apiId,
  displayName,
  description,
});

// add values
colors.addValue("Red");
colors.addValue("Green");

// or add multiple values at a time.
colors.addValue("Blue", "Yellow");

Update a Enumeration

Updating an enumeration and it's values.

const colors = migration.updateEnumeration({
  apiId,
  ... // properties to update.
});

colors.addValue("Black"); // add a new value
colors.updateValue("Red", "Dark Red"); // update existing value
colors.deleteValue("Blue"); // delete value

Delete Enumeration

To delete an enumeration and it's values

migration.deleteEnumeration(apiId);

Models

Your schema is defined by the models you create, and fields you add.

Create a Model

A model can be created by passing in the required parameters.

const modelName = migration.createModel({
  apiId, // must start with upper case letter
  apiIdPlural, // must start with upper case letter
  displayName,
  description,
});

Update a Model

To update a model

migration.updateModel({
  apiId, // required
  ... // properties to update
});

Delete a Model

To delete a model

migration.deleteModel(apiId);

Fields

Your schema is built up of GraphQL types. If you’re familiar working with GraphQL, you should feel right at home. GraphCMS supports all of the common GraphQL types you are used to, as well as some of its own.

Create a Field

To create a simple field.

const { FieldType } = require("@graphcms/management");

model.addSimpleField({
  apiId: '...',
  displayName: '...',
  type: FieldType.String,
});

String fields have several form renderers, including single line, multiline, markdown, and slug. You can set the form renderer as follows:

const { FieldType, Renderer } = require("@graphcms/management");

model.addSimpleField({
  apiId: '...',
  displayName: '...',
  type: FieldType.String,
  formRenderer: Renderer.MultiLine
});

To create an enumerable field.

model.addEnumerableField({
  apiId,
  displayName,
  enumerationApiId, // previously created enumeration.
});

To create a relational field.

const { RelationType } = require("@graphcms/management");

model.addRelationalField({
  apiId,
  displayName,
  relationType: RelationType.OneToOne,
  model, // the related model

  // optional but can be specified to customize the details.
  reverseField: {
    apiId,
    displayName,
  },
});

To create an asset field.

model.addRelationalField({
  apiId,
  displayName,
  model: "Asset", // this is compulsory to indicate Asset field.

  // optional but can be specified to customize the details.
  reverseField: {
    apiId,
    displayName,
  },
});

To create a union field.

const { RelationType } = require("@graphcms/management");

model.addUnionField({
  apiId,
  displayName,
  relationType: RelationType.OneToOne,
  models, // list of related models

  // optional but can be specified to customize the details.
  reverseField: {
    apiId,
    displayName,
  },
});

Update a Field

To update a field, firstly retrieve the model.

const model = migration.updateModel({...}) // to update the model
const model = migration.model(apiId) // to only retrieve the model

Updating simple field

model.updateSimpleField({
  apiId,
  ... // properties to update
})

Updating enumerable field

model.updateEnumerableField({
  apiId,
  ... // properties to update
})

Updating relational field

model.updateRelationalField({
  apiId,
  ... // properties to update
})

Updating union field

model.updateUnionField({
  apiId,
  models, // list of related models
  ... // properties to update
})

Deleting a Field

To delete a field

model.deleteField(apiId);

Contributors

Thanks goes to these wonderful people (emoji key):

Local Development

To update the Management API schema this SDK depends on you must run npm run generate.

PR titles must follow Conventional Commits to publish to NPM automatically.