Hygraph

https://hygraph.com/docs/
Admin
Hygraph is a headless content management system (CMS) that enables teams to manage content creation,...
Tokens:472,988
Snippets:3,590
Trust Score:10
Update:7 months ago
Show doc for...
Tokens:
Raw
### React Setup Page for App Migration

Source: https://hygraph.com/docs/app-framework/migration

This React component demonstrates how to create a setup page for a Hygraph app migration. It uses the `useApp` hook from `@hygraph/app-sdk-react` to access and update installation configuration, specifically an API key. The form submits the API key and sets the installation status to 'COMPLETED'.

```jsx
import { useApp, Wrapper } from '@hygraph/app-sdk-react';


const SetupForm = () => {
  const { installation, updateInstallation } = useApp();
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        updateInstallation({
          config: {
            API_KEY: e.currentTarget.elements.API_KEY.value,
          },
          status: 'COMPLETED',
        });
      }}
    >
      <input type="text" name="API_KEY" />
      <input type="submit" value={'Install App'} />
    </form>
  );
};


const SetupPage = () => {
  return (
    <Wrapper>
      <SetupForm />
    </Wrapper>
  );
};

```

--------------------------------

### Install the Management SDK

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

Install the Hygraph Management SDK package using npm.

```APIDOC
## Install the SDK

Install the Management SDK package via npm:

```bash
npm install @hygraph/management-sdk
```
```

--------------------------------

### Install Hygraph App Next.js Starter

Source: https://hygraph.com/docs/app-framework/quick-starters/nextjs

This command installs the Hygraph App Next.js starter project from a GitHub repository. It uses `create-next-app` to scaffold a new Next.js application with the specified example. Ensure you have Node.js installed.

```bash
npx create-next-app --example https://github.com/hygraph/hygraph-app-nextjs-quick-start docs-example-app
```

--------------------------------

### Install Hygraph Management SDK using npm

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

Installs the Hygraph Management SDK package using npm. This is the first step to programmatically manage your Hygraph project schema.

```bash
npm install @hygraph/management-sdk
```

--------------------------------

### Full Hygraph Management SDK Example (TypeScript)

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

Demonstrates creating a client, adding a model and a field, and then running the migration. Includes error handling for the migration result.

```typescript
import { Client, SimpleFieldType } from '@hygraph/management-sdk';


const client = new Client({
  authToken: '<Permanent auth token>',
  endpoint: '<Content API endpoint>',
});


client.createModel({
    apiId: 'Product',
    apiIdPlural: 'Products',
    displayName: 'Product',
  });


client.createSimpleField({
    parentApiId: 'Product',
    apiId: 'name',
    displayName: 'Name',
    type: SimpleFieldType.STRING,
    isRequired: true,
  });


const result = await client.run(true);
if (result.errors) {
  throw new Error(result.errors);
}


console.log(result);
```

--------------------------------

### Clone Hygraph Blog App Example

Source: https://hygraph.com/docs/implementations/flutter/flutter

Command to clone a pre-built Hygraph Flutter blog application for practice. Requires npx to be installed.

```bash
npx degit https://github.com/hygraph/flutter-hygraph-blog.git
```

--------------------------------

### Start Next.js Development Server

Source: https://hygraph.com/docs/app-framework/first-steps/develop-your-application

Command to start the development server for a Next.js application. After creating the project, navigate to the project directory and run this command to view the application locally.

```bash
yarn dev
```

--------------------------------

### Clone HYGRAPHlix Next Starter

Source: https://hygraph.com/docs/implementations/next/hygraphlix-next

Use this command to clone the HYGRAPHlix starter project, a composable movie platform template, to get started quickly with Next.js and Hygraph.

```bash
npx degit https://github.com/lowisren/hygraph-movie-starter/
```

--------------------------------

### Install Dependencies and Navigate to Project Directory

Source: https://hygraph.com/docs/implementations/astro/microblog-astro

After cloning the project, this command navigates into the project directory and installs all necessary package dependencies using npm.

```bash
cd hygraph-astro-microblog-starter && npm install
```

--------------------------------

### React Field UIX Migration Example

Source: https://hygraph.com/docs/app-framework/migration

This React component shows how to migrate a Field UIX to the Hygraph App Framework. It utilizes the `useFieldExtension` hook from `@hygraph/app-sdk-react` to manage field values and access installation configuration. The `Wrapper` component is used without the `declaration` prop.

```jsx
import { Wrapper, useFieldExtension } from '@hygraph/app-sdk-react';


function MyField() {
  const { value, onChange, installation } = useFieldExtension();
  console.log(installation.config);


  return <input value={value} onChange={(e) => onChange(e.target.value)} />; 
}


export default function MyCustomInputExtensionPage() {
  return (
    // no declaration
    <Wrapper>
      <MyField />
    </Wrapper>
  );
}

```

--------------------------------

### Create a Management SDK Client

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

Initialize the Hygraph Management SDK client with authentication token and endpoint.

```APIDOC
## Create a Management SDK client

Create a new file, for example `management.ts`, and initialize the client with the following parameters:

```javascript
import { Client } from '@hygraph/management-sdk';


const client = new Client({
  authToken,
  endpoint,
  name, // optional
});
```

### Parameters

| Option    | Description
```

--------------------------------

### Example Diff Changes for App Installations

Source: https://hygraph.com/docs/api-reference/schema/environment-diffing

This JSON structure illustrates how app installations and deletions are represented within the diff changes. It shows operations for creating and deleting app installations.

```json
{
  "data": {
    "viewer": {
      "project": {
        "environment": {
          "id": "{envId}",
          "diff": {
            "changes": [
              {
                "createAppInstallation": {
                  "appApiId": "analytics-app",
                  "displayName": "Analytics App",
                  "configuration": {
                    "apiKey": null,
                    "trackingId": null
                  },
                  "status": "INCOMPLETE_SETUP"
                }
              },
              {
                "deleteAppInstallation": {
                  "appApiId": "old-seo-app"
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

--------------------------------

### Install Tailwind CSS in Nuxt

Source: https://hygraph.com/docs/implementations/nuxt/nuxt

Command to install the @nuxtjs/tailwindcss module, which integrates Tailwind CSS into the Nuxt.js project for styling.

```bash
npm install @nuxtjs/tailwindcss
```

--------------------------------

### Initialize New Hygraph Management SDK Client

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

Instantiate the new Hygraph management SDK client by providing authentication token and endpoint. This replaces the `newMigration` named export from the previous SDK.

```typescript
import { Client } from '@hygraph/management-sdk';


const migration = new Client({
  authToken: '...',
  endpoint: '...',
});
```

--------------------------------

### Install GraphQL Client for Remix

Source: https://hygraph.com/docs/implementations/remix/remix

Installs the 'graphql-request' and 'graphql' npm packages as development dependencies. These are used to interact with the Hygraph API.

```bash
npm i -D graphql-request graphql
```

--------------------------------

### Install Nuxt GraphQL Client

Source: https://hygraph.com/docs/implementations/nuxt/nuxt

Installs the nuxt-graphql-client module using npm. This module is essential for GraphQL codegen and simplifies API interactions in Nuxt.js.

```bash
npm install nuxt-graphql-client
```

--------------------------------

### Setup Page for Hygraph App Token Generation (React)

Source: https://hygraph.com/docs/app-framework/app-tokens

This React component, SetupPage, is part of a Next.js application and utilizes the Hygraph App SDK to facilitate the generation of app tokens. It fetches an exchange code from the URL query parameters and passes it to the Setup component, which then makes a POST request to a backend API to obtain and save the app token. It depends on '@hygraph/app-sdk-react' and 'next/router'.

```javascript
import { useApp, Wrapper } from '@hygraph/app-sdk-react';
import { useRouter } from 'next/router';


function Setup({ code }: { code: string }) {
  const { context } = useApp();
  const managementApiBaseUrl = context.project.mgmtApi.split("/")
    .slice(0, -1)
    .join("/");


  return (
    <Button
      onClick={() =>
        fetch(`/api/saveAppToken`, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            code,
            environmentId: context.environment.id,
            managementApiBaseUrl,
          }),
        })
          .then((res) => res.json())
          .then((data) => {
            // Save token to localstorage
            localStorage.setItem('app-token', data.appToken);
          })
      }
    >
      Get App Token
    </Button>
  );
}


// You'll get the exchange code in your setup page as query param only while
// your App Installation is not completed
export default function SetupPage() {
  const { query } = useRouter();
  return (
    <Wrapper>
      <Setup code={query.code as string} />
    </Wrapper>
  );
}

```

--------------------------------

### Install Nuxt Project Dependencies

Source: https://hygraph.com/docs/implementations/nuxt/nuxt

Command to install all project dependencies using npm. This is typically done after initializing a new project or pulling changes.

```bash
npm install
```

--------------------------------

### Run Hygraph Schema Migration (TypeScript)

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

Executes all scheduled schema changes atomically. The 'run()' method submits operations as a batch. It can be called only once per client instance.

```typescript
async run(foreground: boolean = true): Promise<MigrationInfo>
```

--------------------------------

### Create Hygraph Model and Field (New SDK)

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-quickstart

Demonstrates how to create a new model and add a simple field to it using the new Hygraph management SDK. The `modelApiId` must be passed to link the field to the correct model.

```typescript
migration.createModel({
  apiId: 'Post',
  apiIdPlural: 'Posts',
  displayName: 'Post',
});
migration.createSimpleField({
  apiId: 'firstName',
  displayName: 'First Name',
  type: SimpleFieldType.STRING,
  modelApiId: 'Post',
});
```

--------------------------------

### Navigate and Install Dependencies in Next.js Project

Source: https://hygraph.com/docs/implementations/next/next

Commands to change the directory into the newly created Next.js project and install all necessary dependencies. This step is crucial before running the development server.

```bash
cd my-next-project && npm install
```

--------------------------------

### Clone Hygraph E-commerce Starter

Source: https://hygraph.com/docs/getting-started/frontend-creation

Clones the Hygraph e-commerce starter repository to a local directory. This command downloads the starter project, which includes a full-fledged e-commerce frontend template.

```bash
git clone https://github.com/hygraph/hygraph-next-commerce-starter.git
```

--------------------------------

### Run Migration

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

This section provides instructions on how to execute a migration script to apply changes to the Hygraph project.

```APIDOC
## POST /api/migrations/run

### Description
Executes the pending migration operations to apply changes to the Hygraph project.

### Method
POST

### Endpoint
/api/migrations/run

### Parameters
#### Query Parameters
- **apply** (boolean) - Required - Set to `true` to apply changes, `false` for a dry run (though a dedicated dry run endpoint is recommended).

### Request Example
```javascript
async function createBlogSchema() {
  try {
    // ... all operations here ...

    // Execute migration
    const result = await client.run(true); // 'true' to apply changes

    if (result.errors) {
      console.error('Migration failed with errors:', result.errors);
      process.exit(1);
    }

    console.log('Migration completed successfully');
    console.log(`Migration name: ${result.name}`);
    console.log(`Finished at: ${result.finishedAt}`);
  } catch (error) {
    console.error('Migration failed:', error);
    process.exit(1);
  }
}

// To run the migration:
// createBlogSchema();
```

### Environment Variables
- **HYGRAPH_AUTH_TOKEN**: Your Hygraph API token.
- **HYGRAPH_ENDPOINT**: The API endpoint for your Hygraph project.

### Execution Command
```bash
export HYGRAPH_AUTH_TOKEN="your-token"
export HYGRAPH_ENDPOINT="https://your-region.hygraph.com/v2/..."
node create-blog-schema.ts
```

### Response
#### Success Response (200)
- **name** (string) - The name of the migration.
- **finishedAt** (string) - Timestamp when the migration finished.

#### Error Response (non-200)
- **errors** (array) - An array of errors encountered during the migration.

#### Response Example
```json
{
  "name": "migration-12345",
  "finishedAt": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Client Initialization with Migration Name

Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

Illustrates the use of a migration name during client initialization. Reusing the same migration name for subsequent runs will cause the migration to fail. Use unique names for each migration.

```javascript
const client = new Client({
  name: 'create-blog-schema', // First run: OK
  // Second run with same name: FAILS
});
```

--------------------------------

### Hygraph Sidebar UIX Example with React

Source: https://hygraph.com/docs/app-framework/migration

A React component demonstrating a Hygraph sidebar UIX. It utilizes the useFormSidebarExtension hook from '@hygraph/app-sdk-react' to access sidebar extension functionalities. The example includes a simple button that triggers an alert.

```javascript
import { useFormSidebarExtension, Wrapper } from '@hygraph/app-sdk-react';


function SidebarElement() {
  const { extension } = useFormSidebarExtension();
  return (
    <div>
      <h3>Sidebar Example</h3>
      <button onClick={() => alert('Hello, Hygraph!')}>Click Me</button>
    </div>
  );
}


export default function Sidebar() {
  return (
    <Wrapper>
      <SidebarElement />
    </Wrapper>
  );
}

```

--------------------------------

### Full Hygraph Schema Migration Example (JavaScript)

Source: https://hygraph.com/docs/getting-started/fundamentals/migrating-to-hygraph

A comprehensive example demonstrating a schema migration using the `@graphcms/management` SDK. It imports necessary modules, initializes a migration, creates an 'Author' model, adds 'firstName' and 'lastName' fields, and runs the migration.

```javascript
// migration.js
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();
```

--------------------------------

### Basic Hygraph Setup Page Component

Source: https://hygraph.com/docs/app-framework/first-steps/develop-your-application

A simple React component for a Hygraph setup page. It uses the `Wrapper` component from the Hygraph React App SDK. This serves as a placeholder and requires connection to Hygraph to function correctly.

```typescript
import { Wrapper } from '@hygraph/app-sdk-react';


export default function Setup() {
  return <Wrapper>Hello Hygraph</Wrapper>;
}
```

--------------------------------

### Alias Queries for Filtered Results

Source: https://hygraph.com/docs/api-reference/content-api/queries

Demonstrates using query aliases to represent different filtered sets of data within a single request. This example fetches events starting after a specific date and aliases a second query for events starting before that date.

```graphql
{
  events(where: { start_gt: "2020-10-07T09:00:00+00:00" }) {
    start
  }

  previous: events(where: { start_lt: "2020-10-07T09:00:00+00:00" }) {
    start
  }
}
```

--------------------------------

### Create New SvelteKit App

Source: https://hygraph.com/docs/implementations/sveltekit/sveltekit

Command to initialize a new SvelteKit project. This is the first step in setting up your SvelteKit application.

```bash
npm create svelte@latest my-app
```
Tokens:
Raw