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).
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.
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.
Next, give your new Nhost project a name, select a geographic region for your Nhost services and click Create 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.
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.
- From your project workspace, click Connect to GitHub.
- Install the Nhost app on your GitHub account.
- Connect your GitHub repository.
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.
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.
Here are two tips when using the Nhost CLI:
- Use
nhost up -dto run the Nhost CLI in debug mode for more verbose output. - Use
nhost logs -fin 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.
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
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.
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.
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.
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:
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.
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.
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:
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:
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.
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.
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!