The client URL is set to `window.location.origin`, so it can rewrite redirection urls that are
passed on to authenticaion methods. However, `clientUrl` is set to `''` when running on the server
side. This fix then avoid raising an error when trying to rewrite `redirectTo` on non-browser
environment, and forces `useProviderLink` to be rendered on the client side.
Clarifying where nhost client instance should be made for ease of following and understanding the documentation. I think ultimately it should follow the steps shown subsequently.
Update the guide based on Johan's feedback + add a new section at the end to show how to use the GraphQL API to fetch user data + reflect changes from the provided template.
As discussed with Johan. The React template for this guide has also been edited to remove Tailwind CSS and use CSS modules instead.
You can find this template here: https://github.com/gdangelo/cra-template-quickstart-nhost. Please make sure to move it to the Nhost Github repository and publish it to npm.
As discussed with Johan. The Next.js template for this guide has also been edited to remove Tailwind CSS and use CSS modules instead.
You can find this template here: https://github.com/gdangelo/nhost-quickstart-nextjs. Please make sure to move it to the Nhost Github repository.
I ran into an issue where I couldn't sign up users because the auth service wasn't able to connect to mailhog.
That caused the auth service to not send an email and not respond to the HTTP request.
fixes#499
I'm wondering if anyone else had this issue. If I'm the only one then maybe this PR is obsolete.
* fix: correct access to user/session information through getUser/getSession/isReady
* chore: use carret instead of star
* docs: explain all react hooks are available from @nhost/nextjs
* docs: correct imports in nextjs example
* chore: remove orphan changeset
* docs: next.js instead of NextJs
In the next cycle, hasura-auth will only send the refresh token in the hash, and will add the
redirection type as a query parameter. We will then be able to remove/hide the hash from the url as
soon as the refresh token has been used
* chore: rename `@nhost/client` to `@nhost/core`
* chore: refactor hasura-auth-js to use @nhost/core
all existing tests pass
* refactor: adapt syntax to react, and rename machine to authMachine
* refactor: rename to authmachine and remove useless license files
pnpm uses the root license file when publishing packages
* feat: totp login+password
* refactor: passwordless sms, mfa, deanonymize
* refactor: state/value mfa code
* refactor: rename
* refactor: auth status and token change events
* refactor: adjust apollo to original syntax, and sync auth session accross all nhost-js sub-clients
* refactor: revert changelog and adjust documentation
* refactor: adjust to the shape-up signatures
* refactor: make nextjs work with the new system
* refactor: allow async storage getters and setters
* refactor: implement refreshSession
* chore: fix pnpm lock file
* docs: change NhostReactProvider to NhostNextProvider
* chore: changesets
* refactor: change signup/signin hooks signatures as per Johan's request
* refactor: remove `nhost.auth.verifyEmail`
* chore: add changeset
* docs: add mfa to the react example, and adjust examples to the new conventions
* feat: allow oauth providers to get options
* fix: sync sdk client with the machine state
* fix: don't use state.matches and state.hasTag in useSelector, and improve useSelectors
* refactor: set oauth options everywhere, document, and rewrite relative redirectTo
* chore: update pnpm lock file
* fix: correct paths to cjs dist file, and reactivate warning suppression about useLayoutEffect
* chore: keep the same parameters in the React Apollo providers
* refactor: use the new system in @nhost/react-auth, and mark it as deprecated
* chore: @nhost/react-auth changeset
* chore: update pnpm lock file
* docs: remove todos and point to the documenation when it exists
* docs: name files `.tsx` instead of `.jsx`
* refactor: retro-compatible clientStorageType and clientStorage options
* refactor: improve hooks names consistency
See https://github.com/nhost/nhost/pull/273#discussion_r829058348
* chore: don't override changelog
* refactor: bump hasura-auth to version 0.4.2
* refactor: move @apollo/client to a peer dependency
This was the case in the origination @nhost/react-apollo package
* refactor: prettier
* refactor: rename useConfigMfa properties
* chore: ellaborate changesets
* refactor: rename `anonymousSignIn` to `signInAnonymous`
* docs: correct typo
* refactor: rename anonymous signin hook
* refactor: use @nhost/nextjs instead of @nhost/react in Nextjs documentation
* chore: explain renaming from @nhost/client to @nhost/core
* chore: changeset
* chore: complete sentence in changeset
* fix: current options when sign in with a provider
* Create eighty-pianos-try.md
* Create chilled-swans-repeat.md
* send sign-up options
* doesn't hurt to do encodeURIComponent everywhere
Co-authored-by: Pilou <24897252+plmercereau@users.noreply.github.com>
* export refresh utilitly function
For being able to receive a new accessToken on client side it would be ideal to expose the `refresh` function.
* Create loud-planets-impress.md
Co-authored-by: Pilou <24897252+plmercereau@users.noreply.github.com>
- We use [pnpm](https://pnpm.io/) as a package manager to speed up development and builds, and as a basis for our monorepo. You need to make sure it's installed on your machine. There are [several ways to install it](https://pnpm.io/installation), but the easiest way is with `npm`:
```sh
$ npm install -g pnpm
```
- Our tests and examples use the Nhost CLI, to run the backend services locally. You can follow the installation instructions in [our documentation](https://docs.nhost.io/get-started/cli-workflow/install-cli).
## Get started
### Installation
First, clone this repository:
```sh
git clone https://github.com/nhost/nhost
```
Then, install the dependencies with `pnpm`:
```sh
$ cd nhost
$ pnpm install
```
### Development
Although package references are correctly updated on the fly for TypeScript, example projects won't
see the changes because they are depending on the build output. To fix this, you can run packages
in development mode.
Running packages in development mode is as simple as:
```sh
$ pnpm dev
```
Our packages are linked together using [PNPM's workspace](https://pnpm.io/workspaces) feature. Vite automatically detects changes in the dependencies and rebuilds everything, so that the changes are immediately reflected in the other packages.
### Use examples
Examples are a great way to test your changes in practice. Make sure you've `pnpm dev` running in your terminal and then run an example.
Let's follow the instructions to run [react-apollo example](https://github.com/nhost/nhost/blob/main/examples/react-apollo/README.md).
## Run the documentation website locally
The easier way to contribute to our documentation is to go to the `docs` folder and follow the [instructions to start local development](https://github.com/nhost/nhost/blob/main/docs/README.md):
```sh
$ cd docs
# not necessary if you've already done this step somewhere in the repository
$ pnpm install
$ pnpm start
```
## Run test suites
### Unit tests
You can run the unit tests with the following command from the repository root:
```sh
$ pnpm test
```
### End-to-end tests
Each package that defines end-to-end tests embeds their own Nhost configuration, that will be automatically when running the tests. As a result, you must make sure you are not running the Nhost CLI before running the tests.
You can run the e2e tests with the following command from the repository root:
```sh
$ pnpm e2e
```
## Changesets
If you've made changes to the packages, you must describe those changes so that they can be reflected in the next release.
We use [changesets](https://github.com/changesets/changesets) to support our versioning and release workflows. When you submit a pull request, a bot checks if some changesets are present, and if not, it directs you to add them.
The most comprehensive way to add a changeset is to run the following command in the repository root:
```sh
$ pnpm changeset
```
This will create a file in the `.changeset` directory. You can edit it to give more details about the change you just made.
You can take a look at the changeset documentation: [How to add a changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).
## Committing changes
You'll notice that `git commit` takes a few seconds to run. We set a commit hook that scans the changes in the code, automatically generates documentation from the inline [TSDoc](https://tsdoc.org/) annotations, and adds these generated documentation files to the commit. They automatically update the [reference documentation](https://docs.nhost.io/reference).
**Nhost is a serverless backend for web and mobile apps** built with the following things in mind:
**Nhost is an open source Firebase alternative with GraphQL,** built with the following things in mind:
- Open Source
- Developer Productivity
- SQL
- GraphQL
- SQL
- Great Developer Experience
Nhost consists of open source software:
@@ -36,21 +36,30 @@ Nhost consists of open source software:
- Serverless Functions: Node.js (JavaScript and TypeScript)
- [Nhost CLI](https://docs.nhost.io/reference/cli) for local development
## Architecture of Nhost
<div align="center">
<br />
<img src="assets/nhost-diagram.png"/>
<br />
<br />
</div>
Visit [https://docs.nhost.io](http://docs.nhost.io) for the complete documentation.
# How to get started
# Get Started
### Option 1: One-click deployment with Nhost (recommended)
## Option 1: Nhost Hosted Platform
1.Create [Nhost account](https://app.nhost.io) (you can use GitHub to sign up)
2. Create Nhost app
3. Done!
1.Sign in to [Nhost](https://app.nhost.io).
2. Create Nhost app.
3. Done.
### Option 2: Self-hosting
## Option 2: Self-hosting
Since Nhost is 100% open source, you can self-host the whole Nhost stack. Check out the example [docker-compose file](https://github.com/nhost/nhost/tree/main/examples/docker-compose) to self-host Nhost.
## Sign in a user and make your first GraphQL query
## Sign In and Make a Graphql Request
Install the `@nhost/nhost-js` package and start build your app:
@@ -58,7 +67,8 @@ Install the `@nhost/nhost-js` package and start build your app:
@@ -101,18 +112,312 @@ First and foremost: **Star and watch this repository** to stay up-to-date.
Also, follow Nhost on [GitHub Discussions](https://github.com/nhost/nhost/discussions), our [Blog](https://nhost.io/blog), and on [Twitter](https://twitter.com/nhostio). You can chat with the team and other members on [Discord](https://discord.com/invite/9V7Qb2U) and follow our tutorials and other video material at [YouTube](https://www.youtube.com/channel/UCJ7irtvV9Y0EQMxpabb6ntg?view_as=subscriber).
## Nhost is Open Source
### Nhost is Open Source
This repository, and most of our other open source projects, are licensed under the MIT license.
<img style="width: 260px; height: 56px" src="https://runacap.com/wp-content/uploads/2022/06/ROSS_badge_black_Q1_2022.svg" alt="ROSS Index - Fastest Growing Open-Source Startups in Q1 2022 | Runa Capital" width="260" height="56" />
</a>
### How to contribute
Here are some ways of contributing to making Nhost better:
- **[Try out Nhost](https://docs.nhost.io/get-started/quick-start)**, and think of ways to make the service better. Let us know here on GitHub.
- Join our [Discord](https://discord.com/invite/9V7Qb2U) and connect with other members to share and learn from.
- Send a pull request to any of our [open source repositories](https://github.com/nhost) on Github. Check our [contribution guide](https://github.com/nhost/nhost/blob/main/CONTRIBUTING.md) for more details about how to contribute. We're looking forward to your contribution!
- Send a pull request to any of our [open source repositories](https://github.com/nhost) on Github. Check our [contribution guide](https://github.com/nhost/nhost/blob/main/CONTRIBUTING.md) and our [developers guide](https://github.com/nhost/nhost/blob/main/DEVELOPERS.md) for more details about how to contribute. We're looking forward to your contribution!
## Security
### Contributors
If you discover a security vulnerability within Nhost, please e-mail [security@nhost.io](mailto:security@nhost.io). All security vulnerabilities will be promptly addressed.
This documentation describes how to build, start and test the documentation locally.
1. Install dependencies: `yarn`
2. Start dev server: `yarn dev`
### Installation
## NOTES;
The content is copied from the main `nhost/nhost` repo. This repo is only to modify styles/react components.
## Structure
The `order.ts` file contains the main order for the entire structure of `posts`. The keys are `categories` and the values are `subcategories` in which contains the order the posts.
Metadata such as the `title` of the file that appears on the nav is on the frontmatter of each markdown file. The file name becomes the final url. Each top-level folder appears on the header as main navigation, each subfolder becomes a main subcategory of the nav and posts are included under each subcategory.
### Local Development
In order to create a new file you place it its proper subcategory and modify the category on the `order.ts` file such as `sdk: ["javascript-sdk", "react-auth", "react-apollo"],` -> `sdk: ["javascript-sdk", "react-auth", "vue"]`
```bash
$ pnpm start
```
Each subCategory e.g. `reference` or `tutorials` has an `index.mdx` file. If a new subcategory is added, a file has to be created for it.
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
### Build
```bash
$ pnpm build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
### Serve
```bash
$ pnpm serve
```
This command serves the static content from the `build` directory.
### Contributing
All pull requests are greatly appreciated! See our [contributing guide](https://github.com/nhost/nhost/blob/main/CONTRIBUTING.md) to get started.
You defined `select` permissions for the `public` role in the previous section. You will now add `insert` and `create` permissions for authenticated users to secure your app's GraphQL API with authentication.
> Nhost's authentication service lets you deliver frictionless registration and login experiences to your users. We support most social providers and different methods such as email & password and passwordless (magic link).
---
## Insert a test user
Manually create a user by going to your app's **Users** tab (top menu) and clicking on **Add User**.
You will now use that newly created user to make authenticated requests to the API.
---
## Authenticate and query data
Add the following code to sign in the new user and request the list of todos again:
```js
import { NhostClient } from '@nhost/nhost-js'
const nhost = new NhostClient({
backendUrl: 'https://[app-subdomain].nhost.run'
})(async () => {
// Sign in user
const signInResponse = await nhost.auth.signIn({
email: 'joe@example.com',
password: 'securepassword'
})
// Handle sign-in error
if (signInResponse.error) {
throw signInResponse.error
}
// Get todos
const todos = await nhost.graphql.request(`
query {
todos {
id
created_at
name
is_completed
}
}
`)
console.log(JSON.stringify(todos.data, null, 2))
})()
```
Why is the return value `null`? Because when making GraphQL requests as an authenticated user, the `user` role is assumed.
> For authenticated requests, there is always the option to override the default `user` role with any other valid role.
---
## Permissions for users
### Remove permissions for the public role
We won't use the `public` role anymore, so let's remove all permission for that role.
Now we'll add permissions for the `user` role.
> All logged-in users have the `user` role.
### Insert permission
First, we'll set the **Insert permission**.
A user can only insert `name` because all other columns will be set automatically. More specifically, `user_id` is set to the user's id making the request (`x-hasura-user-id`) and is configured in the `Column presets` section. See the image below.
For **Select permission**, set a **custom check** so users can only select todos where `user_id` is the same as their user id. In other words: users are only allowed to select their own todos. See the image below.
In the previous tutorials, we tested various parts of Nhost, such as:
- Database
- GraphQL API
- Permission
- JavaScript SDK
- Authentication
All changes we did to our database and API happened directly in production of our Nhost app.
It’s not ideal for making changes in production because you might break things, which will affect all users of your app.
Instead, it’s recommended to make changes and test your app locally before deploying those changes to production.
To do changes locally, we need to have a complete Nhost app running locally, which the Nhost CLI does.
The Nhost CLI matches your production application in a local environment, this way you can make changes and test your code before deploying your changes to production.
## Recommended workflow with Nhost
1. Develop locally using the Nhost CLI.
2. Push changes to GitHub.
3. Nhost automatically applies changes to production.
>💡 Make sure you have [Docker](https://www.docker.com/get-started) installed on your computer. It’s required for Nhost to work.
The `nhost dev` command will automatically start a complete Nhost environment locally on your computer using:
- Postgres
- Hasura
- Authentication
- Storage
- Serverless Functions
- Mailhog
You use this local environment to do changes and testing before you deploy your changes to production.
Running `nhost dev` also starts the Hasura Console.
>💡 It’s important that you use the Hasura Console that is started automatically when you do changes. This way, changes are automatically tracked for you.
When we created the `customers` table there was also a migration created automatically. The migration was created at under `nhost/migrations/default`.
```bash
$ ls -la nhost/migrations/default
total 0
drwxr-xr-x 3 eli staff 96 Feb 7 16:19 .
drwxr-xr-x 3 eli staff 96 Feb 7 16:19 ..
drwxr-xr-x 4 eli staff 128 Feb 7 16:19 1644247179684_create_table_public_customers
```
This database migration has only been applied locally, meaning, you created the `customers` table locally but it does not (yet) exists in production.
To apply the local change to production we need to commit the changes and push it to GitHub. Nhost will then automatically pick up the change in the repository and apply the changes.
<aside>
💡 You can commit and push files in another terminal while still having `nhost dev` running.
</aside>
```sql
git add -A
git commit -m "Initialized Nhost and added a customers table"
git push
```
Head over to the **Deployments** tab in the **Nhost console** to see the deployment.
Once the deployment finishes the `customers` table is created in production.
We’ve now completed the recommended workflow with Nhost:
In the previous section, we only created a new table; `customers`. Using the CLI you can also do changes to other parts of your backend.
There are three things the CLI and the GitHub integration track and applies to production:
1. Database migrations
2. Hasura Metadata
3. Serverless Functions
For this section, let’s do one change to the Hasura metadata and create one serverless function
### Hasura Metadata
We’ll add permissions to the `users` table, making sure users can only see their own data. For this, go to the `auth` schema and click on the `users` table. then click on **Permissions** and enter a new role **user** and create a new **select** permission for that role**.**
We can now test the function locally. Locally, the backend URL is `http://localhost:1337`. Functions are under `/v1/functions`. And every function’s path and filename becomes an API endpoint.
This means our function `functions/time.ts` is at `http://localhost:1337/v1/functions/time`.
Let’s use curl to test our new function:
```bash
curl http://localhost:1337/v1/functions/time
Hello undefined! It's now: Sun, 06 Feb 2022 17:44:45 GMT
What follows is a detailed tutorial on how you setup Nhost for this workflow
### Create Nhost App
Create a **new Nhost app** for this tutorial.
> It’s important that you create a **new** Nhost app for this guide instead of reusing an old Nhost app because we want to start with a clean Nhost app.
### Create new GitHub Repository
Create a new GitHub repository for your new Nhost app. The repo can be either private or public.
## Connect GitHub Repository to Nhost App
In the Nhost Console, go to the dashboard of your Nhost app and click **Connect to GitHub**.
Let's create a simple todo-app using Nhost. In a todo-app, a user should be able to create list items for their account (CRUD) and not have anyone else see them (permissions).
To implement this todo-app with Nhost, we'll briefly cover these topics:
- Creating a new app on Nhost
- Defining a database schema
- Inserting data
- Setting permissions
- Querying data via the GraphQL API
By the end of this quick-start, you will better understand what Nhost is and what it does for you.
---
## Log in to Nhost
Go to [app.nhost.io](https://app.nhost.io) and sign up for a new account if you don't have one already.
---
## Create app
Press the **"New App"** button on the console's home page. Choose a name and pick the region closest to your users.
You'll be all set with the Default Workspace and the Free plan for now.
Creating a new app takes around 20 seconds or so. During this time, Nhost sets up your app's entire backend and infrastructure.
Once the setup completes, you'll automatically see the app dashboard, and you're ready to define your app's database schema.
In the previous section, you used the Hasura Console to fetch a list of todos. Now, you will write a small JavaScript client to interact and retrieve todos from your Nhost app.
### Frontend frameworks
Nhost is framework-agnostic and works with any frontend you might build. You can also connect to Nhost from your server-side if you wish.
In this guide, we'll keep the example simple. We're not using a frontend framework. In a real-life scenario, you'd probably build a frontend client with a framework such as React, Vue, Svelte or React Native.
---
## Setup
> Make sure you have [Node.js](https://nodejs.org) and [npm](https://docs.npmjs.com/getting-started) installed.
Create a new folder called `nhost-todos`, and initialize a new JavaScript app there:
```sh
npm init -y
# or
yarn init -y
```
> You might have to edit the `package.json` file and add/change the `type` object to `module` (`"type": "module"`).
Install Nhost JavaScript SDK:
```sh
npm install @nhost/nhost-js
# or
yarn add @nhost/nhost-js
```
---
## Initialize Nhost
In the new directory, create a file called `index.js`.
Enter the following code into this file. It will initialize a new `NhostClient` that will interact with your backend:
```js
import { NhostClient } from '@nhost/nhost-js'
const nhost = new NhostClient({
backendUrl: 'https://[app-subdomain].nhost.run' // replace this with the backend URL of your app
})
console.log(nhost.graphql.getUrl())
```
Run the code in your terminal. You should see your app's GraphQL endpoint URL:
```sh
➜ node index.js
https://[app-subdomain].nhost.run/v1/graphql
```
### Query todos
If you now add the following GraphQL query to the client, let's see what happens when you run the updated version:
```js
import { NhostClient } from '@nhost/nhost-js'
const nhost = new NhostClient({
backendUrl: 'https://[app-subdomain].nhost.run'
})(async () => {
// nhost.graphql.request returns a promise, so we use await here
In the previous section, you could fetch the todos because the **admin** role is enabled by default when using Hasura Console. When building your applications, you want to define permissions using **roles** that your users can assume when making requests.
Hasura supports role-based access control. You create rules for each role, table, and operation (select, insert, update and delete) that can check dynamic session variables, like user ID.
## Unauthenticated users
Use the `public` role in permissions when you want some data to be accessed by anyone without being signed in. The `public` role is the default role in all unauthenticated requests.
Generally speaking, the `public` role should not have insert, update or delete permissions defined.
### Setting `public` permissions
In Hasura Console, go to the **Data** tab, click on the **todos** table, then click **Permissions**. Add a new role called `public` and click on **select**. The permission options for the select operation show up below.
1. Nhost sets the `public` role for every unauthenticated GraphQL request.
2. You explicitly defined permissions for the `public` role.
It is essential to understand that Hasura has an **allow nothing by default** policy to ensure that only roles and permissions you define explicitly have access to the GraphQL API.
To implement an app for managing a todo list, let's ensure we have database tables for storing todos and users.
---
## Open Hasura Console
Hasura generates real-time GraphQL APIs, but it also provides a web console for manipulating the schema and data of your database.
Go to the **Data** tab on your app's dashboard and select **Open Hasura**. Remember to copy the admin secret.
The Hasura Console of your app's dedicated Hasura instance will open in a new tab. You can use Hasura Console to manage your app's schema, data, permissions, and event triggers.
---
## Users table
You should see all your database tables on the left-hand side of the screen. You should see multiple different **schemas** displayed as folders:
- `public` schema for your app's custom tables
- `auth` and `storage` schemas for Nhost's user management and file storage
If you open the `auth` schema, you'll see that your app already has a `users` table, so you don't have to create one.
---
## Create todos table
In Hasura Console, go to the **data** tab, then click **Create Table**. Name this table `todos`.
### Add frequently used columns
`id` and `created_at` columns are standard and can be added with two clicks. Click **Frequently used columns** and create them:
- `id` (UUID)
- `created_at` (timestamp)
Using frequently used columns ensures the columns get the right name, type, and default value.
### Add custom columns
Add two more columns manually:
- `name` (text)
- `is_completed` (boolean)
Make sure to set the default value of `is_completed` to `false`.
This is all we need! A new table will be created when you click **Add Table**.
---
## Insert data
Go to the **Insert Row** tab to add some data to your database.
Now that we have data in our database, we can retrieve it via a GraphQL API. Go to the **API** tab in the main menu. You can use this view to make GraphQL requests that query or mutate data in your database.
Paste the following GraphQL query into the form and press the "play" button:
```graphql
query {
todos {
id
created_at
name
is_completed
}
}
```
You should see the todos you just inserted show up as output on the right-hand side.
### Admin role
All requests in the Hasura Console use the `admin` role by default. This role has access to all tables and permissions.
Upgrading from Nhost v1 to v2 requires database schema and Hasura metadata changes.
---
## Upgrade Steps
### Create a new Nhost v2 app locally
> Make sure you have the [Nhost CLI](/reference/cli) installed
```sh
nhost init my-nhost-v2-app
cd my-nhost-v2-app
```
### Update config
Update `config: 3` to `config: 2` in `nhost/config.yaml`. This will update Hasura's configuration version, and we need to downgrade the version when we export migrations and metadata.
### Export current migrations and metadata from Nhost v1
Make the following changes manually to your migrations.
> The migration file is located at `nhost/migrations/[timestamp]/up.sql`.
- Add `OR REPLACE` after `CREATE` for the `public.set_current_timestamp_updated_at` function
- Delete all `auth.*` tables and functions (if any).
- Delete `public.users` table and everything related to the table such as constraints, triggers, etc.
- Update FK references from `public.users` to `auth.users` (if any).
### Update Metadata
Make the following changes manually to your metadata.
> The metadata is located at `nhost/metadata/tables.yaml`.
- Delete tracking all tables in the `auth` schema.
- Delete tracking the `public.users` table.
- Update all references to `users` from the `public` to `auth` schema.
### Start nhost
Start Nhost locally using the [CLI](/reference/cli). From the root of your app, run:
```sh
nhost -d
```
> Running Nhost applies your local database migrations and Hasura metadata.
### Restart Auth and Storage containers
Open Docker UI and restart Hasura Auth and Hasura Storage. Restarting those containers applies new metadata, effectively tracking everything in the `auth` and the `storage` schema.
### Delete migrations and metadata
Delete the local migrations and metadata.
```
rm -rf nhost/migrations nhost/metadata
```
### Update config (again)
Update `config: 2` to `config: 3` in `nhost/config.yaml`.
### Pull migrations and metadata from our local instance
> You can not use port `1337` in these requests. You have to use the specific port Huasra uses. Go to the Hasura Console under API and look what port Hasura is using under GraphQL Endpoint.
The following emails can be sent as part of the authentication flow:
- Sign up confirmation email (when using email + password)
- Reset password email (when using email + password)
- Passwordless login email (when using Magic Link)
- Confirm email change (any sign-up method)
---
## Enabling custom email templates
If you have developed custom email templates, you must make them available over HTTP and then point Nhost to them. You can host the templates on your server, or use a public repository on GitHub.
Go to **Users -> Login settings** and scroll down to **Custom email templates**, and set the URL to where your templates are located:
You only need to define the base URL to point to your hosted templates. The UI will give you a hint about where Nhost will look for your actual template files.
---
## File structure
The email templates should be provided as body.html and subject.txt files in this predefined folder structure:
```txt
// At base URL (e.g. https://yourapp.com/email-templates/)
en/
email-confirm-change/
body.html
subject.txt
email-verify/
body.html
subject.txt
password-reset/
body.html
subject.txt
signin-passwordless/
body.html
subject.txt
// Other language versions
fr/
/* ... */
se/
/* ... */
```
You don’t have to provide all templates - only the one you wish to use and customize. For the templates you do provide, you must provide both body.html and subject.txt.
[View example on GitHub](https://github.com/nhost/nhost/tree/main/examples/custom-email-templates)
---
## Localisation
If Nhost finds a template that matches the recipent user’s locale, the email will be sent in that language. Use two-letter language codes to set the locale.
English will always be used as the default if another language version is not found.
---
## Template variables
Use variables like `${displayName}` to make your templates more dynamic:
Nhost provides a ready-to-use authentication service, integrated with Nhost JavaScript SDK. This makes it easy to build login flows with multiple login methods.
---
## Getting started
Using [Nhost JavaScript SDK](/reference/sdk), sign up a new user:
```js
import { NhostClient } from '@nhost/nhost-js'
const nhost = new NhostClient({
backendUrl: 'https://[app-subdomain].nhost.run'
})
await nhost.auth.signUp({
email: 'joe@nhost.io',
password: 'secret-password'
})
```
---
## How it works
1. A user signs up and the user information is added to the `auth.users` table
2. Nhost returns an access token (JWT token) with the user's information. The access token is cryptographically signed.
3. The user sends a request to the GraphQL API together with the access token.
4. The GraphQL API reviews the access token to ensure the user is authorized to send the request.
Nhost's authentication service is integrated with your database. All users are saved in the app's database under the `auth` schema and can be accessed using GraphQL:
```graphql
query {
users {
id
displayName
avatarUrl
email
}
}
```
---
## Tokens
Nhost authentication uses two tokens: Access tokens and refresh tokens.
[Nhost JavaScript SDK](/sdk/) automatically handles access and refresh tokens.
### Access tokens
An access token is used to authenticate and authorize a user when doing a GraphQL request.
Access tokens are cryptographically signed and cannot be revoked. They are only valid for 15 minutes. Users can request a new valid access token with a refresh token.
An access token includes a user's ID and roles. Here's an example:
To sign in a user with email and password, the user must first sign up:
```js
await nhost.auth.signUp({
email: 'joe@nhost.io',
password: 'secret-password'
})
```
If you've turned on email verification in your app's **login settings**, a user will be sent a verification email upon signup. The user must click the verification link in the email before they can log in.
Once a user has been signed up (and optionally verified), you can sign them in:
```js
await nhost.auth.signIn({
email: 'joe@nhost.io',
password: 'secret-password'
})
```
---
## Passwordless email (magic link)
Users can sign in with passwordless email, also called magic link.
When a user signs in with passwordless email, Nhost will create the user if they don't already exist and send an email to the user.
When a user clicks the link in the email, they will be redirected to your app and automatically signed in.
Example in JavaScript:
```js
await nhost.auth.signIn({
email: 'joe@nhost.io'
})
```
---
## Passwordless SMS
Users can sign in with passwordless SMS. The passwordless SMS sign in method has a flow:
First, "sign in" the user with a phone number.
```js
await nnhost.auth.signIn({
phoneNumber: '+467610337135'
})
```
This will create the user if the user does not already exist, and send a One Time Password (OTP) to the user's
phone number.
Use the OTP to finalize the sign-in:
```js
await nhost.auth.signIn({
phoneNumber: '+467610337135',
otp: 'otp-from-sms'
})
```
---
## Anonymous
A user can be created anonymously. This is useful for offering a limited version of your application to your users without having them sign in first.
An anonymous user gets a user ID with the `anonymous` role. This role can be used to [set permissions in Hasura](/platform/database/permissions).
### Deanonymize users
Anonymous users can be converted to "normal" users by deanonymize the user.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
