Nhost

https://docs.nhost.io/
Admin
Nhost is a backend-as-a-service platform that helps developers build, deploy, and scale applications...
Tokens:470,252
Snippets:3,727
Trust Score:9.2
Update:2 hours ago
Show doc for...
Tokens:
Raw
### startDevSession query example

Source: https://docs.nhost.io/reference/graphql/ai/mutation/start-dev-session

Example GraphQL query to start a developer session, requesting sessionID, assistantID, userID, and createdAt fields.

```graphql
query startDevSession {
  graphite {
    startDevSession {
      sessionID
      assistantID
      userID
      createdAt
    }
  }
}
```

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

### startSession Query Example

Source: https://docs.nhost.io/reference/graphql/ai/mutation/start-session

Example GraphQL query to start a session. It uses a variable $assistantID and requests sessionID, assistantID, userID, and createdAt fields.

```graphql
query startSession (
  $assistantID: String!
) {
  graphite {
    startSession (
      assistantID: $assistantID
    ) {
      sessionID
      assistantID
      userID
      createdAt
    }
  }
}
```

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

### createClient Usage Examples

Source: https://docs.nhost.io/reference/javascript/nhost-js/main

Examples of creating a client with default URLs, custom service URLs, cookie-based session storage, and additional custom middleware. The examples show various configuration options for the createClient function.

```javascript
// Create client using Nhost cloud default URLs
const nhost = createClient({
  subdomain: "abcdefgh",
  region: "eu-central-1",
});

// Create client with custom service URLs
const customNhost = createClient({
  authUrl: "https://auth.example.com",
  storageUrl: "https://storage.example.com",
  graphqlUrl: "https://graphql.example.com",
  functionsUrl: "https://functions.example.com",
});

// Create client using cookies for storing the session
import { CookieStorage } from "@nhost/nhost-js/session";

const nhost = createClient({
  subdomain: "abcdefgh",
  region: "eu-central-1",
  storage: new CookieStorage({
    secure: import.meta.env.ENVIRONMENT === "production",
  }),
});

// Create client with additional custom middleware
const nhost = createClient({
  subdomain: "abcdefgh",
  region: "eu-central-1",
  configure: [customLoggingMiddleware],
});
```

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

### Start development server (npm run start)

Source: https://docs.nhost.io/getting-started/tutorials/reactnative/2-protected-routes

Runs the development server to test the screen protection implementation. After starting, open the app in Expo Go; when not signed in, the home screen shows a message and the profile button is hidden.

```bash
npm run start
```

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

### Install Nhost CLI via Bun

Source: https://docs.nhost.io/getting-started/local-development/cli

Install the Nhost CLI globally using Bun.

```bash
bun add -g @nhost/cli
```

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

### Install Nhost CLI via Homebrew

Source: https://docs.nhost.io/getting-started/local-development/cli

Install the Nhost CLI using Homebrew.

```bash
brew install nhost/tap/nhost
```

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

### Install Nhost CLI via Nix

Source: https://docs.nhost.io/getting-started/local-development/cli

Install the Nhost CLI using Nix.

```bash
nix profile install github:nhost/nhost#cli
```

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

### Install Nhost CLI via npm

Source: https://docs.nhost.io/getting-started/local-development/cli

Install the Nhost CLI globally using npm.

```bash
npm install -g @nhost/cli
```

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

### createNhostClient() usage examples

Source: https://docs.nhost.io/reference/javascript/nhost-js/main

Three examples showing how to create a basic client, a client with custom middleware, and an admin client. The basic client uses no middleware, the custom client uses withClientSideSessionMiddleware and withChainFunctions, and the admin client uses withAdminSession with an admin secret and session variables.

```javascript
// Create a basic client with no middleware
const nhost = createNhostClient({
  subdomain: "abcdefgh",
  region: "eu-central-1",
  configure: [],
});

// Create a client with custom configuration
const nhost = createNhostClient({
  subdomain: "abcdefgh",
  region: "eu-central-1",
  configure: [
    withClientSideSessionMiddleware,
    withChainFunctions([customLoggingMiddleware]),
  ],
});

// Create an admin client
const nhost = createNhostClient({
  subdomain,
  region,
  configure: [
    withAdminSession({
      adminSecret: "nhost-admin-secret",
      role: "user",
      sessionVariables: {
        "user-id": "54058C42-51F7-4B37-8B69-C89A841D2221",
      },
    }),
  ],
});
```

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

### Start local development environment with nhost up cloud

Source: https://docs.nhost.io/platform/cli/cloud-development

Sets environment variables and starts the local development environment connected to your cloud project. Replace placeholders with your project subdomain and Postgres connection string.

```bash
export SUBDOMAIN=your-project-subdomain
export POSTGRES_URL=your-complete-postgres-url
nhost up cloud --subdomain $SUBDOMAIN --postgres-url $POSTGRES_URL
```

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

### Start Nhost with `--apply-seeds` to pre-populate database

Source: https://docs.nhost.io/platform/cli/seeds

Starts the Nhost development environment and automatically applies all seeds. The output shows migrations, metadata, and seeds being applied successfully.

```bash
$ nhost up --apply-seeds
Setting up Nhost development environment...
Starting Nhost development environment...

(...) omitted for brevity

Applying migrations...
INFO migrations applied on database: default
Applying metadata...
INFO Metadata applied
Applying seeds...
INFO Seed data planted for database: default

(...) omitted for brevity
```

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

### Install Express types for TypeScript editor support

Source: https://docs.nhost.io/products/functions/local-development

Install the Express types as a dev dependency to get editor support when writing TypeScript functions.

```bash
npm install -D @types/express
```

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

### GraphQL query to get a single user

Source: https://docs.nhost.io/products/auth/users

Example query to retrieve a single user by ID.

```graphql
query {
  user(id: "<user-id>") {
    id
    displayName
    email
    metadata
  }
}
```

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

### startDevSession response example

Source: https://docs.nhost.io/reference/graphql/ai/mutation/start-dev-session

Example JSON response from the startDevSession mutation, showing the returned session data with assistantID, createdAt, sessionID, and userID.

```json
{
  "data": {
    "graphite": {
      "startDevSession": {
        "assistantID": "string",
        "createdAt": "2023-12-14T07:45:15.20353+00:00",
        "sessionID": "string",
        "userID": "61809D37-DA3F-4EFC-A324-EB181F38DD85"
      }
    }
  }
}
```

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

### GraphQL query to get all users

Source: https://docs.nhost.io/products/auth/users

Example query to retrieve all users with id, displayName, email, and metadata.

```graphql
query {
  users {
    id
    displayName
    email
    metadata
  }
}
```

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

### Initialize project from Nhost Cloud

Source: https://docs.nhost.io/getting-started/local-development/cli

Pulls configuration from an existing Nhost Cloud project. Requires authentication.

```bash
nhost init --remote
```

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

### createServerClient() for Express reading session from a cookie

Source: https://docs.nhost.io/reference/javascript/nhost-js/main

Example using Express with cookie-parser. The storage get reads from req.cookies.nhostSession; set and remove throw errors because session handling is easier on the client.

```typescript
// Example for express reading session from a cookie

import express, { Request, Response } from "express";
import cookieParser from "cookie-parser";

app.use(cookieParser());

const nhostClientFromCookies = (req: Request) => {
  return createServerClient({
    subdomain: "local",
    region: "local",
    storage: {
      get: (): StoredSession | null => {
        const s = req.cookies.nhostSession || null;
        if (!s) {
          return null;
        }
        const session = JSON.parse(s) as StoredSession;
        return session;
      },
      set: (_value: StoredSession) => {
        throw new Error("It is easier to handle the session in the client");
      },
      remove: () => {
        throw new Error("It is easier to handle the session in the client");
      },
    },
  });
};
```

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

### HTML img tag for authenticated files (won't work)

Source: https://docs.nhost.io/products/storage/guides/display-images

A plain <img> tag makes an unauthenticated GET request, which will be rejected for files that require authentication. This example is shown as the problem to avoid.

```html
<!-- This won't work for authenticated files -->
<img src="https://local.storage.local.nhost.run/v1/files/FILE_ID" />
```

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

### Create movies table and insert sample data

Source: https://docs.nhost.io/getting-started/quickstart/sveltekit

Run this SQL in the Nhost Dashboard's SQL Console to create a `movies` table and insert sample movie records. Ensure the 'Track this' option is enabled.

```sql
CREATE TABLE movies (
  id SERIAL PRIMARY KEY,
  title VARCHAR(255) NOT NULL,
  director VARCHAR(255),
  release_year INTEGER,
  genre VARCHAR(100),
  rating FLOAT
);

INSERT INTO movies (title, director, release_year, genre, rating) VALUES
  ('Inception', 'Christopher Nolan', 2010, 'Sci-Fi', 8.8),
  ('The Godfather', 'Francis Ford Coppola', 1972, 'Crime', 9.2),
  ('Forrest Gump', 'Robert Zemeckis', 1994, 'Drama', 8.8),
  ('The Matrix', 'Lana Wachowski, Lilly Wachowski', 1999, 'Action', 8.7);
```

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

### Setting custom subdomain via environment variable and CLI flag

Source: https://docs.nhost.io/platform/cli/subdomain

Shows how to start the development environment with a custom subdomain using NHOST_LOCAL_SUBDOMAIN or --local-subdomain, and the resulting URLs and SDK configuration.

```bash
> export NHOST_LOCAL_SUBDOMAIN=192-168-1-1-8 # either this or --local-subdomain 192-168-1-108
> nhost --local-subdomain 192-168-1-108 up
...
Nhost development environment started.
URLs:
- Postgres:         postgres://postgres:postgres@localhost:5432/local
- Hasura:           https://192-168-1-108.hasura.local.nhost.run
- GraphQL:          https://192-168-1-108.graphql.local.nhost.run
- Auth:             https://192-168-1-108.auth.local.nhost.run
- Storage:          https://192-168-1-108.storage.local.nhost.run
- Functions:        https://192-168-1-108.functions.local.nhost.run
- Dashboard:        https://192-168-1-108.dashboard.local.nhost.run
- Mailhog:          https://192-168-1-108.mailhog.local.nhost.run

SDK Configuration:
 Subdomain:    192-168-1-108
 Region:       local
Run `nhost up` to reload the development environment
Run `nhost down` to stop the development environment
Run `nhost logs` to watch the logs

```

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

### GitHub Actions workflow for Nhost deployment

Source: https://docs.nhost.io/platform/cloud/deployments

Example GitHub Actions workflow using the `nhost-actions/deploy` action to trigger deployments from CI/CD. It checks out the repository, installs the Nhost CLI, authenticates with a PAT, and deploys. The action accepts inputs like `subdomain`, `git_ref`, `message`, `user`, `user_avatar_url`, and `timeout` (default 300 seconds).

```yaml
name: Deploy to Nhost

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: nhost-actions/install-nhost-cli@v1

      - uses: nhost-actions/authenticate@v1
        with:
          pat: ${{ secrets.NHOST_PAT }}

      - uses: nhost-actions/deploy@v1
        with:
          subdomain: <your-subdomain>
```

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

### Start Expo Development Server with npx expo start

Source: https://docs.nhost.io/getting-started/tutorials/reactnative/4-graphql-operations

Run this command to start the Expo development server for your React Native application. After starting, you can test all the functionality described in the tutorial.

```bash
npx expo start
```

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

### clearSession example

Source: https://docs.nhost.io/reference/javascript/nhost-js/main

Example usage of clearSession to log out the user.

```javascript
// Log out the user
nhost.clearSession();
```

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

### Configure Nhost client (src/lib/nhost.js)

Source: https://docs.nhost.io/getting-started/quickstart/sveltekit

Create a Nhost client instance with your project's subdomain and region. Replace the placeholders with your actual values.

```javascript
import { createClient } from "@nhost/nhost-js";

// Replace <subdomain> and <region> with your project's values
export const nhost = createClient({
  subdomain: "<subdomain>",
  region: "<region>",
})
```

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

### Install Nhost SDK and AsyncStorage dependencies

Source: https://docs.nhost.io/getting-started/tutorials/reactnative/2-protected-routes

Installs the Nhost JavaScript SDK, AsyncStorage, Expo Router, and Expo Constants using Expo's install command.

```bash
npx expo install @nhost/nhost-js @react-native-async-storage/async-storage@~2 expo-router@~6 expo-constants@~18
```

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

### getUserSession example

Source: https://docs.nhost.io/reference/javascript/nhost-js/main

Example usage of getUserSession to check if a user is authenticated.

```javascript
const session = nhost.getUserSession();
if (session) {
  console.log("User is authenticated:", session.user.id);
} else {
  console.log("No active session");
}
```

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

### Create Nhost client and use auth, storage, GraphQL, and functions

Source: https://docs.nhost.io/reference/javascript/nhost-js/main

Create a client instance with subdomain and region, then sign up with email/password, upload files, make a GraphQL request, and call a serverless function. The session is persisted and auto-refreshed. The output shows the response structures for each operation.

```javascript
const nhost = createClient({
  subdomain,
  region,
});

// Sign in with email/password
// This will create a session and persist it in the storage
// Subsequent calls will use the session from the storage
// If the session is about to expire, it will be refreshed
// automatically
await nhost.auth.signUpEmailPassword({
  email,
  password,
});

// upload a couple of files
const uplFilesResp = await nhost.storage.uploadFiles({
  "file[]": [
    new File(["test1"], "file-1", { type: "text/plain" }),
    new File(["test2 is larger"], "file-2", { type: "text/plain" }),
  ],
});
console.log(JSON.stringify(uplFilesResp, null, 2));
// {
//   "data": {
//     "processedFiles": [
//       {
//         "id": "c0e83185-0ce5-435c-bd46-9841adc30699",
//         "name": "file-1",
//         "size": 5,
//         "bucketId": "default",
//         "etag": "\"5a105e8b9d40e1329780d62ea2265d8a\"",
//         "createdAt": "2025-05-09T17:26:04.579839+00:00",
//         "updatedAt": "2025-05-09T17:26:04.589692+00:00",
//         "isUploaded": true,
//         "mimeType": "text/plain",
//         "uploadedByUserId": "3357aada-b6c7-4af1-9655-1307ca2883a2",
//         "metadata": null
//       },
//       {
//         "id": "3f189004-21fd-42d0-be1d-1ead021ab167",
//         "name": "file-2",
//         "size": 15,
//         "bucketId": "default",
//         "etag": "\"302e888c5e289fe6b02115b748771ee9\"",
//         "createdAt": "2025-05-09T17:26:04.59245+00:00",
//         "updatedAt": "2025-05-09T17:26:04.596831+00:00",
//         "isUploaded": true,
//         "mimeType": "text/plain",
//         "uploadedByUserId": "3357aada-b6c7-4af1-9655-1307ca2883a2",
//         "metadata": null
//       }
//     ]
//   },
//   "status": 201,
//   "headers": {
//     "content-length": "644",
//     "content-type": "application/json; charset=utf-8",
//     "date": "Fri, 09 May 2025 17:26:04 GMT"
//   }
// }

// make a GraphQL request to list the files
const graphResp = await nhost.graphql.request({
  query: `
     query {
       files {
         name
         size
         mimeType
       }
     }
   `,
});

console.log(JSON.stringify(graphResp, null, 2));
// {
//   "body": {
//     "data": {
//       "files": [
//         {
//           "name": "file-1",
//           "size": 5,
//           "mimeType": "text/plain"
//         },
//         {
//           "name": "file-2",
//           "size": 15,
//           "mimeType": "text/plain"
//         }
//       ]
//     }
//   },
//   "status": 200,
//   "headers": {}
// }

// make a request to a serverless function
const funcResp = await nhost.functions.post("/helloworld", {
  message: "Hello, World!",
});
console.log(JSON.stringify(funcResp.body, null, 2));
// {
//   "message": "Hello, World!"
// }
```

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

### Install @nhost/stripe-graphql-js with pnpm

Source: https://docs.nhost.io/products/graphql/guides/stripe

Install the package in your Nhost project using pnpm.

```bash
pnpm add @nhost/stripe-graphql-js
```

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

### startDevSession variables example

Source: https://docs.nhost.io/reference/graphql/ai/mutation/start-dev-session

Empty variables object for the startDevSession query.

```json
{}
```

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

### Initialize a new Nhost project

Source: https://docs.nhost.io/getting-started/local-development/cli

Scaffolds a new Nhost project in the current directory, creating a nhost/ directory with backend configuration and a functions/ directory for serverless functions.

```bash
nhost init
```

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

### Install graphql and graphql-yoga

Source: https://docs.nhost.io/products/functions/guides/graphql-server

Install the required npm packages for GraphQL Yoga.

```bash
npm install graphql graphql-yoga
```

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

### Install @nhost/nhost-js

Source: https://docs.nhost.io/getting-started/quickstart/sveltekit

Install the Nhost JavaScript SDK package in your SvelteKit application.

```bash
npm install @nhost/nhost-js
```

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

### Show help for nhost run config-deploy

Source: https://docs.nhost.io/products/run/configuration-overlays

Displays the help output for `nhost run config-deploy`, which automatically applies the overlay with the same name as the service ID if it exists. The help shows the available options including `--config` and `--service-id`.

```bash
$ nhost run config-deploy --help
NAME:
   nhost run config-deploy - Deploy service configuration

USAGE:
   nhost run config-deploy [command options] [arguments...]

OPTIONS:
   --config value      Service configuration file (default: "nhost-run-service.toml") [$NHOST_RUN_SERVICE_CONFIG]
   --service-id value  Service ID to update. Applies overlay of the same name [$NHOST_RUN_SERVICE_ID]
   --help, -h          show help
```

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

### refreshSession example

Source: https://docs.nhost.io/reference/javascript/nhost-js/main

Example usage of refreshSession to refresh tokens proactively or force a refresh.

```javascript
// Refresh token if it's about to expire in the next 5 minutes
const refreshedSession = await nhost.refreshSession(300);

// Force refresh regardless of current token expiration
const forcedRefresh = await nhost.refreshSession(0);
```

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

### Install MCP with Cursor

Source: https://docs.nhost.io/platform/cli/mcp/development-setup

Paste this prompt into Cursor's Agent chat to let the AI assistant set up the Nhost MCP server for your local project.

```text
Set up the Nhost MCP server for my local project: https://docs.nhost.io/install-mcp
```

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

### deleteSession Variables Example

Source: https://docs.nhost.io/reference/graphql/ai/mutation/delete-session

Example variables object for the deleteSession query, providing the sessionID.

```json
{
  "sessionID": "string"
}
```

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

### Install jsonwebtoken dependencies

Source: https://docs.nhost.io/products/functions/guides/custom-jwts

Install the jsonwebtoken package and its TypeScript types as dev dependencies.

```bash
npm install jsonwebtoken
npm install -D @types/jsonwebtoken
```
Tokens:
Raw