{"id":20216750,"url":"https://github.com/hygraph/management-sdk","last_synced_at":"2025-03-16T13:11:31.929Z","repository":{"id":42519562,"uuid":"350759824","full_name":"hygraph/management-sdk","owner":"hygraph","description":"Hygraph Management SDK","archived":false,"fork":false,"pushed_at":"2024-09-13T18:56:48.000Z","size":312,"stargazers_count":51,"open_issues_count":9,"forks_count":17,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-03-16T04:56:08.256Z","etag":null,"topics":["automation","hygraph","management-sdk","migration-tool"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hygraph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-23T15:18:23.000Z","updated_at":"2025-02-21T20:07:41.000Z","dependencies_parsed_at":"2024-09-14T09:39:20.261Z","dependency_job_id":null,"html_url":"https://github.com/hygraph/management-sdk","commit_stats":null,"previous_names":["graphcms/management-sdk"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygraph%2Fmanagement-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygraph%2Fmanagement-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygraph%2Fmanagement-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hygraph%2Fmanagement-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hygraph","download_url":"https://codeload.github.com/hygraph/management-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243871904,"owners_count":20361380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","hygraph","management-sdk","migration-tool"],"created_at":"2024-11-14T06:29:33.994Z","updated_at":"2025-03-16T13:11:31.891Z","avatar_url":"https://github.com/hygraph.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e@hygraph/management\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eProgrammatically manage Hygraph project schema via migrations.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://npmjs.org/package/@hygraph/management-sdk\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@hygraph/management-sdk.svg\" alt=\"Version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://npmjs.org/package/@hygraph/management-sdk\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dw/@hygraph/management-sdk.svg\" alt=\"Downloads/week\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hygraph/management-sdk/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/l/@hygraph/management-sdk.svg\" alt=\"License\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hygraph/management-sdk/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/hygraph/management-sdk\" alt=\"Forks on GitHub\" /\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://badgen.net/bundlephobia/minzip/@graphcms/management\" alt=\"minified + gzip size\" /\u003e\n  \u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n  \u003cimg src=\"https://img.shields.io/badge/all_contributors-1-purple.svg\" alt=\"Contributors\" /\u003e\n  \u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n  \u003cbr/\u003e\n  \u003ca href=\"https://slack.hygraph.com\"\u003eJoin us on Slack\u003c/a\u003e • \u003ca href=\"https://app.hygraph.com\"\u003eLogin to Hygraph\u003c/a\u003e • \u003ca href=\"https://x.com/hygraph\"\u003e@hygraph\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n⚠️ **@graphcms/management has been deprecated and will no longer receive support. Please use [@hygraph/management-sdk](https://www.npmjs.com/package/@hygraph/management-sdk) instead. Follow [this](https://hygraph.com/docs/api-reference/developer-tools/management-sdk#migration) guide to migrate to the new SDK. More information on the new SDK can be found [here](https://hygraph.com/docs/api-reference/developer-tools/management-sdk).** ⚠️\n\n---\n\n## Quickstart\n\n```js\nconst { newMigration, FieldType } = require(\"@hygraph/management-sdk\");\n\nconst migration = newMigration({ endpoint: \"...\", authToken: \"...\" });\n\nconst author = migration.createModel({\n  apiId: \"Author\",\n  apiIdPlural: \"Authors\",\n  displayName: \"Author\",\n});\n\nauthor.addSimpleField({\n  apiId: \"firstName\",\n  displayName: \"First Name\",\n  type: FieldType.String,\n});\nauthor.addSimpleField({\n  apiId: \"lastName\",\n  displayName: \"Last Name\",\n  type: FieldType.String,\n});\n\nmigration.run();\n```\n\n## Install\n\n```bash\nnpm install @hygraph/management-sdk --save-dev\n```\n\n## Usage\n\nChanges to your schema starts with a migration.\n\n### New Migration\n\nA migration is scoped to an environment. To create a migration, the following parameters are required.\n\n- **Authentication Token `authToken`.**\n\n  Can be retrieved from `Settings \u003e API Access` on https://app.hygraph.com\n\n- **Environment URL `endpoint`.**\n\n  Can be retrieved from `Settings \u003e Environments` on https://app.hygraph.com\n\n- **Migration Name `name` [optional].**\n\n  Every migration has a unique name. If unspecified, a name would be generated and will be part of the response of a successful migration.\n\n  Subsequent migrations with same name will fail.\n\n```js\nconst { newMigration } = require(\"@hygraph/management-sdk\");\n\nconst migration = newMigration({\n  authToken,\n  endpoint,\n  name, // optional\n});\n```\n\n### Running a Migration\n\nThe `run` method runs the migration.\n\nBy default, migrations run in the background. Passing an optional boolean argument configures the migration to run in the foreground.\n\n```js\nconst foreground = true;\n\nconst result = migration.run(foreground);\n\nif (result.errors) {\n  console.log(result.errors);\n} else {\n  console.log(result.name);\n}\n```\n\n### Dry Run a Migration\n\nA migration can be dry run to preview what changes would be applied.\n\n```js\nconst changes = migration.dryRun();\n\nconsole.log(changes);\n```\n\n## Updating an Entity\n\nTo update properties, specify the properties to be updated. All ommitted properties remain unmodified.\n\nAs a special case, `apiId` is a requirement because all entities are uniquely indentified by `apiId`.\n\nTo update the `apiId`, specify `newApiId`.\n\n## Locales\n\nHygraph boasts a flexible localization API that you can use to publish content for all or specific locales in your project.\n\n### Create a Locale\n\nTo create a locale\n\n```js\nmigration.createLocale({\n  apiId,\n  displayName,\n  description,\n});\n```\n\n### Update a Locale\n\nTo update a locale\n\n```js\nmigration.updateLocale({\n  apiId,\n  ... // properties to update\n});\n```\n\n### Delete a Locale\n\nTo delete a locale\n\n```js\nmigration.deleteLocale(apiId);\n```\n\n## Stages\n\nYou can create your own content stages, and query content from these stages, as well as publish to.\n\n### Create a Stage\n\nTo create a stage\n\n```js\nmigration.createStage({\n  apiId,\n  displayName,\n  description,\n  isDefault,\n  allowQueries,\n  color,\n});\n```\n\n### Update a Stage\n\nTo update a stage\n\n```js\nmigration.updateStage({\n  apiId,\n  ... // properties to update\n});\n```\n\n### Delete a Stage\n\nTo delete a Stage\n\n```js\nmigration.deleteStage(apiId);\n```\n\n## Enumerations\n\nEnums values can only contain alphanumeric characters, and underscores.\n\n### Create a Enumeration\n\nCreate an enumeration with values.\n\n```js\nconst colors = migration.createEnumeration({\n  apiId,\n  displayName,\n  description,\n});\n\n// add values\ncolors.addValue(\"Red\");\ncolors.addValue(\"Green\");\n\n// or add multiple values at a time.\ncolors.addValue(\"Blue\", \"Yellow\");\n```\n\n### Update a Enumeration\n\nUpdating an enumeration and it's values.\n\n```js\nconst colors = migration.updateEnumeration({\n  apiId,\n  ... // properties to update.\n});\n\ncolors.addValue(\"Black\"); // add a new value\ncolors.updateValue(\"Red\", \"Dark Red\"); // update existing value\ncolors.deleteValue(\"Blue\"); // delete value\n```\n\n### Delete Enumeration\n\nTo delete an enumeration and it's values\n\n```js\nmigration.deleteEnumeration(apiId);\n```\n\n## Models\n\nYour schema is defined by the models you create, and fields you add.\n\n### Create a Model\n\nA model can be created by passing in the required parameters.\n\n```js\nconst modelName = migration.createModel({\n  apiId, // must start with upper case letter\n  apiIdPlural, // must start with upper case letter\n  displayName,\n  description,\n});\n```\n\n### Update a Model\n\nTo update a model\n\n```js\nmigration.updateModel({\n  apiId, // required\n  ... // properties to update\n});\n```\n\n### Delete a Model\n\nTo delete a model\n\n```js\nmigration.deleteModel(apiId);\n```\n\n### Fields\n\nYour schema is built up of GraphQL types. If you’re familiar working with GraphQL, you should feel right at home. Hygraph supports all of the common GraphQL types you are used to, as well as some of its own.\n\n#### Create a Field\n\nTo create a simple field.\n\n```js\nconst { FieldType } = require(\"@hygraph/management-sdk\");\n\nmodel.addSimpleField({\n  apiId: '...',\n  displayName: '...',\n  type: FieldType.String,\n});\n```\n\nString fields have several [form renderers](/src/renderer.ts#L4-L10), including single line, multiline, markdown, and slug. You can set the form renderer as follows:\n\n```js\nconst { FieldType, Renderer } = require(\"@hygraph/management-sdk\");\n\nmodel.addSimpleField({\n  apiId: '...',\n  displayName: '...',\n  type: FieldType.String,\n  formRenderer: Renderer.MultiLine\n});\n```\n\nTo create an enumerable field.\n\n```js\nmodel.addEnumerableField({\n  apiId,\n  displayName,\n  enumerationApiId, // previously created enumeration.\n});\n```\n\nTo create a relational field.\n\n```js\nconst { RelationType } = require(\"@hygraph/management-sdk\");\n\nmodel.addRelationalField({\n  apiId,\n  displayName,\n  relationType: RelationType.OneToOne,\n  model, // the related model\n\n  // optional but can be specified to customize the details.\n  reverseField: {\n    apiId,\n    displayName,\n  },\n});\n```\n\nTo create an asset field.\n\n```js\nmodel.addRelationalField({\n  apiId,\n  displayName,\n  model: \"Asset\", // this is compulsory to indicate Asset field.\n\n  // optional but can be specified to customize the details.\n  reverseField: {\n    apiId,\n    displayName,\n  },\n});\n```\n\nTo create a union field.\n\n```js\nconst { RelationType } = require(\"@hygraph/management-sdk\");\n\nmodel.addUnionField({\n  apiId,\n  displayName,\n  relationType: RelationType.OneToOne,\n  models, // list of related models\n\n  // optional but can be specified to customize the details.\n  reverseField: {\n    apiId,\n    displayName,\n  },\n});\n```\n\n#### Update a Field\n\nTo update a field, firstly retrieve the model.\n\n```js\nconst model = migration.updateModel({...}) // to update the model\nconst model = migration.model(apiId) // to only retrieve the model\n```\n\nUpdating simple field\n\n```js\nmodel.updateSimpleField({\n  apiId,\n  ... // properties to update\n})\n```\n\nUpdating enumerable field\n\n```js\nmodel.updateEnumerableField({\n  apiId,\n  ... // properties to update\n})\n```\n\nUpdating relational field\n\n```js\nmodel.updateRelationalField({\n  apiId,\n  ... // properties to update\n})\n```\n\nUpdating union field\n\n```js\nmodel.updateUnionField({\n  apiId,\n  models, // list of related models\n  ... // properties to update\n})\n```\n\n#### Deleting a Field\n\nTo delete a field\n\n```js\nmodel.deleteField(apiId);\n```\n\n## Contributors\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n## Local Development\n\nTo update the Management API schema this SDK depends on you must run `npm run generate`.\n\nPR titles must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to publish to NPM automatically.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhygraph%2Fmanagement-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhygraph%2Fmanagement-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhygraph%2Fmanagement-sdk/lists"}