Nothing's plumb meaningless

    @graphcms/management
    TypeScript icon, indicating that this package has built-in type declarations

    1.4.0 • Public • Published

    @graphcms/management

    Programmatically manage GraphCMS project schema via migrations.

    Version Downloads/week License Forks on GitHub minified + gzip size Contributors
    Join us on SlackLogin 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);

    Remote Type Definitions

    Remote fields allow you to define an external resolver through the management SDK. Remote fields consist of two parts, defining any custom type that will represent the returning shape from the external resolver, defining the resolver itself.

    Create a Remote Type Definition

    Create a sample Remote Type Definition for Github API.

    migration.createRemoteTypeDefinition({
      definition:
        "type Github { id: Int!, login: String!, name: String!, company: String, bio: String, blog: String, location: String }",
      displayName: "Github profile",
      description: "Developer's Github profile",
    });

    Update a Remote Type Definition

    To update a Remote Type Definition

    migration.updateRemoteTypeDefinition({
      apiId:
      ... // properties to update
    });

    Delete a Remote Type Definition

    To delete a Remote Type Definition

    migration.deleteRemoteTypeDefinition(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,
      },
    });

    To create a remote field.

    model.addRemoteField({
      apiId,
      displayName,
      remoteConfig: {
        method, // one of GET (default), POST or PUT.
        payloadFieldApiIds, // Array<String> of field API IDs to send as part of request payload
        returnType, // previously declared remote type definition
        url, // url to fetch the remote data from
      },
    });

    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.

    Keywords

    none

    Install

    npm i @graphcms/management

    DownloadsWeekly Downloads

    457

    Version

    1.4.0

    License

    MIT

    Unpacked Size

    1.43 MB

    Total Files

    32

    Last publish

    Collaborators

    • mahaveergcms
    • martian2lee
    • harish027
    • graphcms-owner
    • feychenie
    • notrab
    • somus
    • jpedroschmitz
    • eljuli
    • larisachristie