Skip to main content

Local Development

Nhost's command-line interface (CLI) lets you run a complete Nhost development environment locally with the following services: PostgreSQL database, Hasura, Authentication, Storage (MinIO), Serverless Functions, and Emails (Mailhog).

Installation

Install the Nhost CLI

To install Nhost CLI, run this command from any directory in your terminal:

sudo curl -L https://raw.githubusercontent.com/nhost/cli/main/get.sh | bash

The Nhost CLI works for MacOS, Linux, and Windows WSL2.

The Nhost CLI is installed at /usr/local/bin.

If you'd prefer to install the CLI at a different location other than /usr/local/bin, set the INSTALL_PATH variable accordingly:

sudo curl -L https://raw.githubusercontent.com/nhost/cli/main/get.sh | INSTALL_PATH=$HOME/bin bash

You can move the executable to a different location and add the path to the environment variable PATH to make nhost accessible globally.

Finally, you can check that everything has been successfully installed by typing:

nhost version

Prerequisites

Dependencies

Before using the Nhost CLI, make sure you have the following dependencies installed on your local machine:

Nhost CLI Login

After installing Nhost CLI, you can log in to your Nhost account by running the following command:

nhost login

This will display a prompt for you to enter your Nhost account credentials (email/password).

info

If you've signed up with GitHub you must first set a new password in the Nhost Dashboard to use to sign in with the Nhost CLI.

Nhost CLI Login

After successfully logging in, you are authorized to manage your Nhost projects using the Nhost CLI.

Set Up Your Project

1. Create a new Nhost project

First things first, we need to create a new Nhost project.

So, log in to your Nhost dashboard and click the Create Your First Project button.

Nhost Dashboard

Next, give your new Nhost project a name, select a geographic region for your Nhost services and click Create Project.

New Nhost project

After a few seconds, you should get a PostgreSQL database, a GraphQL API with Hasura, file storage, and authentication set up.

2. Create a New GitHub Repository

A typical workflow would also include creating a Github repository for your Nhost project. It will facilitate your development workflow since Nhost can integrate with Github to enable continuous deployment.

So, go to your Github account and create a new repository. You can make your repository either public or private.

Create GitHub Repo

3. Connect Nhost Project to Github

Finally, connect your GitHub repository to your Nhost project. Doing so will enable Nhost to deploy new versions of your project when you push new commits to your connected Git repository.

  1. From your project workspace, click Connect to GitHub.

Connect to GitHub

  1. Install the Nhost app on your GitHub account.

Connect to GitHub

  1. Connect your GitHub repository.

Connect to GitHub

Local Development

1. Initialize your Nhost Project

Nhost CLI brings the functionality of your Nhost production environment directly to your local machine.

It provides Docker containers to run the backend services that match your production environment in a local environment. That way, you can make changes and test your code locally before deploying those changes to production.

Initialize your Nhost project locally with the following command:

nhost init --remote

It will prompt you to choose what Nhost project you want to initialize.

Select Nhost Project

Your file system will be populated with the following files and folders:

my-nhost-app/
└─ nhost/
├─ config.yaml
├─ emails/
├─ metadata/
├─ migrations/
└─ seeds/

Finally, make sure to link your current working directory to your GitHub repository:

echo "# my-nhost-app" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/[github-username]/my-nhost-app.git
git push -u origin main

2. Start a local development environment

To start a local development environment for your Nhost project, run the following command:

nhost up

Running this command will start up all the backend services provided by Nhost.

info

Here are two tips when using the Nhost CLI:

  1. Use nhost up -d to run the Nhost CLI in debug mode for more verbose output.
  2. Use nhost logs -f in a different terminal to see local logs for your Nhost project.

nhost up starts Hasura Console for the GraphQL Engine so you can manage the database and test the GraphQL API.

The Hasura Console opens automatically at http://localhost:9695.

Hasura Console

3. Make Changes

There are three things the Nhost CLI and the GitHub integration track and apply to production:

  • Database Migrations
  • Hasura Metadata
  • Serverless Functions
caution

Settings in nhost/config.yaml are not deployed. That means you need to manually sync settings between local and remote environments between the CLI and Nhost Cloud.

Database Migrations

Database changes are automatically tracked and managed through migrations.

tip

You must use the Hasura Console to make database changes. With the Hasura Console, database migration files are automatically generated incrementally to track database changes for you.

To demonstrate how to make database changes, let's create a new table called messages, with the following columns:

- `id` (type UUID and default `gen_random_uuid()`),
- `text` (type Text),
- `authorId` (type UUID),
- `createdAt` (type Timestamp and default `now()`)

In the Hasura Console, go to the DATA tab section and click on the PostgreSQL database (from the left side navigation) that Nhost provides us.

Click on the public schema and then the Create Table button.

Create Table

Enter the values for creating the messages table as mentioned above.

Also, specify the id column as the primary key of the table, and link the authorId column to the users.id column using a foreign key to link the users and messages tables together.

Create Table

Next, click on the Add Table button to create the table.

Finally, check out the migrations/ folder in your project directory. A migration file has been created automatically to reflect our database changes and track the new table creation.

The migration was created under nhost/migrations/default:

$ ls -la nhost/migrations/default
total 0
drwxr-xr-x 3 user staff 96 Apr 27 17:06 .
drwxr-xr-x 3 user staff 96 Apr 27 17:06 ..
drwxr-xr-x 4 user staff 128 Apr 27 17:06 1651071963431_create_table_public_messages

Note that this database migration has only been applied locally. In other words, the messages table does not (yet) exists in production.

To apply the local changes to production, check out the Deploy your project section below.

Hasura metadata

In addition to database schema changes, Nhost also tracks Hasura metadata.

The Hasura metadata track all the actions performed on the console, like tracking tables/views/functions, creating relationships, configuring permissions, creating event triggers, and remote schemas.

To demonstrate it, let's add a new permission to our messages table for the user role on the insert operation. That permission will allow users to create new messages.

So, open the permissions tab for the messages table, type in user in the role cell, and click the edit icon on the insert operation:

Create Table

To restrict the users to create new messages only for themselves, specify an _eq condition between the authorId and the X-Hasura-User-ID session variable, which is passed with each request.

Create Table

Then, select the columns the users can define through the GraphQL API, set the value for the authorId column to be equal to the X-Hasura-User-ID session variable, and click Save Permissions.

Create Table

Finally, check out the metadata/ folder in your project directory to confirm that the permission changes we did were tracked locally in your git repository.

In our case, those changes should be tracked in nhost/metadata/databases/default/tables/public_messages.yaml:

nhost/metadata/databases/default/tables/public_messages.yaml
table:
name: messages
schema: public
insert_permissions:
- permission:
backend_only: false
check:
authorId:
_eq: X-Hasura-User-Id
columns:
- text
set:
authorId: x-hasura-User-Id
role: user

Serverless Functions

Now let's create a Serverless Function before we push all changes to GitHub so Nhost can deploy them to production.

For this guide, let's create a Serverless Function that will return the current date-time when called.

First, make sure to install express, which is required for serverless functions to work.

npm install express
npm install -d @types/node @types/express

Then, create a new file named time.ts inside the functions/ folder of your working directory, and paste the following code:

functions/time.ts
import { Request, Response } from 'express'

export default (req: Request, res: Response) => {
return res.status(200).send(`Hello ${req.query.name}! It's now: ${new Date().toUTCString()}`)
}

Every JavaScript and TypeScript file inside the functions/ folder becomes an API endpoint.

Locally, the base URL for the serverless functions is http://localhost:1337/v1/functions. Then, the endpoint for each function is determined by its filename or the name of its dedicated parent directory.

For example, the endpoint for our function is http://localhost:1337/v1/functions/time.

curl http://localhost:1337/v1/functions/time\?name\=Greg
Hello Greg! It's now: Wed, 27 Apr 2022 18:52:12 GMT

4. Managing Local Data

Nhost makes it easy to manage data on different branches. Within your project directory there is an .nhost directory that tracks database configuration, database seeds, mail data, and functions.

Seed Data

See the section on seed data for an overview.

If seeds have been applied there will be a file seeds.applied within the .nhost/data/<branch-name>/db directory.

If you need to re-apply your seeds, delete this file and restart nhost.

Deploy your project

To deploy your local changes to production, you can commit and push them to GitHub. As a result, Nhost will automatically pick up the changes in your repository and apply them to your associated remote Nhost project.

caution

Make sure to connect your Github repository to your Nhost project first.

git add -A
git commit -m "commit message"
git push

To check out your deployment, head over to the Deployments tab in your Nhost dashboard.

Deployments

Get help

To get usage tips and learn more about available commands from within Nhost CLI, run the following:

nhost help

For more information about a specific command, run the command with the --help flag:

nhost init --help

If you have additional questions or ideas for new features, you can start an issue or a new discussion on Nhost CLI’s open-source repository. You can also chat with our team on Discord.

We’d love to hear from you!