From e21f68bd42dd633d02dbbdd72cdc3dfa92bc5212 Mon Sep 17 00:00:00 2001 From: Andrew Smith Date: Sun, 13 Aug 2023 12:40:23 +0000 Subject: [PATCH 01/10] Add docs for email template in local supabase --- .../NavigationMenu.constants.ts | 4 +++ .../cli/customizing-email-templates.mdx | 31 ++++++++++++++++++ spec/cli_v1_config.yaml | 32 +++++++++++++++++++ 3 files changed, 67 insertions(+) create mode 100644 apps/docs/pages/guides/cli/customizing-email-templates.mdx diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index f12d0ecd7f8..bb27d1cd08e 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -1037,6 +1037,10 @@ export const supabase_cli: NavMenuConstant = { name: 'Testing and linting', url: '/guides/cli/testing-and-linting', }, + { + name: 'Customizing email templates', + url: '/guides/cli/customizing-email-templates', + }, ], }, { diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx new file mode 100644 index 00000000000..d1ba4360cde --- /dev/null +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -0,0 +1,31 @@ +import Layout from '~/layouts/DefaultGuideLayout' + +export const meta = { + id: 'customizing-email-templates', + title: 'Customizing email teplates', + description: 'Customizing local email templates using config.toml.', +} + +The Supabase CLI uses a `config.toml` file to manage local configuration. This file is located in the `supabase` directory of your project. + +## Config reference + +The `config.toml` file is automatically created when you run `supabase start`. + +There are a wide variety of options available, which can be found in the [CLI Config Reference](/docs/reference/cli/config). + +For example, to update the "Invite" email subject and content for local development, you can append the following information to `config.toml`: + +```toml +[auth.email.template.invite] +subject = "You are invited to Acme Inc" +content_path = "./supabase/auth/email/invite.html" +``` + +The `content_path` should contain the html file you are pointing to otherwise the CLI won't start the project. + +> Note: These settings are only for local development, if you want to use the same content for your hosted Supabase you will need to copy and paste these into the Supabase Dashboard + +export const Page = ({ children }) => + +export default Page diff --git a/spec/cli_v1_config.yaml b/spec/cli_v1_config.yaml index 308a3e0c4ae..1726e69d937 100644 --- a/spec/cli_v1_config.yaml +++ b/spec/cli_v1_config.yaml @@ -260,6 +260,38 @@ parameters: links: - name: 'Auth Server configuration' link: 'https://supabase.com/docs/reference/auth' + + - id: 'auth.email.template.type.subject' + title: 'auth.email.template..subject' + tags: ['auth'] + required: false + description: | + The full list of email template types are: + + - `invite` + - `confirmation` + - `recovery` + - `magic_link` + - `email_change` + links: + - name: 'Auth Server configuration' + link: 'https://supabase.com/docs/reference/auth' + + - id: 'auth.email.template.type.content_path' + title: 'auth.email.template..content_path' + tags: ['auth'] + required: false + description: | + The full list of email template types are: + + - `invite` + - `confirmation` + - `recovery` + - `magic_link` + - `email_change` + links: + - name: 'Auth Server configuration' + link: 'https://supabase.com/docs/reference/auth' - id: 'auth.external.provider.enabled' title: 'auth.external..enabled' From 26ea918ea8961132463ee37af6696b325fd9822e Mon Sep 17 00:00:00 2001 From: Ant Wilson Date: Mon, 14 Aug 2023 16:33:46 +0200 Subject: [PATCH 02/10] Update apps/docs/pages/guides/cli/customizing-email-templates.mdx --- apps/docs/pages/guides/cli/customizing-email-templates.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index d1ba4360cde..97c223ee287 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -2,7 +2,7 @@ import Layout from '~/layouts/DefaultGuideLayout' export const meta = { id: 'customizing-email-templates', - title: 'Customizing email teplates', + title: 'Customizing email templates', description: 'Customizing local email templates using config.toml.', } From b74d714ea6b468cfe486bd84d17163174ee000e1 Mon Sep 17 00:00:00 2001 From: Andrew Smith Date: Tue, 15 Aug 2023 11:49:37 +0000 Subject: [PATCH 03/10] Update with email template variables --- .../cli/customizing-email-templates.mdx | 25 ++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index 97c223ee287..8a9e905dcba 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -24,7 +24,30 @@ content_path = "./supabase/auth/email/invite.html" The `content_path` should contain the html file you are pointing to otherwise the CLI won't start the project. -> Note: These settings are only for local development, if you want to use the same content for your hosted Supabase you will need to copy and paste these into the Supabase Dashboard + + +These settings are only for local development, if you want to use the same content for your hosted Supabase instance you will need to copy and paste these into the Supabase Dashboard + + + +### Email template variables + +The following template variables are available inside of your email template. + +``` +{{ .ConfirmationURL }} : URL to confirm the email change +{{ .Token }} : The 6-digit numeric email OTP +{{ .TokenHash }} : The hashed token used in the URL +{{ .SiteURL }} : The URL of the site +{{ .Email }} : The original users email address +{{ .NewEmail }} : The users new email address +``` + + + +`{{ .NewEmail }}` is only available in the email_change email template + + export const Page = ({ children }) => From 450ddabcfa79f1eb25c1f9771df0066b9440df3b Mon Sep 17 00:00:00 2001 From: Andrew Smith Date: Tue, 15 Aug 2023 13:09:53 +0000 Subject: [PATCH 04/10] Update the formatting of the template variables --- .../guides/cli/customizing-email-templates.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index 8a9e905dcba..0de1dd95101 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -32,16 +32,16 @@ These settings are only for local development, if you want to use the same conte ### Email template variables -The following template variables are available inside of your email template. +The templating system provides the following variables for use: -``` -{{ .ConfirmationURL }} : URL to confirm the email change -{{ .Token }} : The 6-digit numeric email OTP -{{ .TokenHash }} : The hashed token used in the URL -{{ .SiteURL }} : The URL of the site -{{ .Email }} : The original users email address -{{ .NewEmail }} : The users new email address -``` +| Name | Description | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `{{ .ConfirmationURL }}` | Contains the confirmation URL. For example, a signup confirmation URL would look like: `https://project-ref.supabase.co/auth/v1/verify?token={{ .TokenHash }}&type=signup&redirect_to=https://example.com/path` . | +| `{{ .Token }}` | Contains a 6-digit One-Time-Password (OTP) that can be used instead of the `{{. ConfirmationURL }}` . | +| `{{ .TokenHash }}` | Contains a hashed version of the `{{ .Token }}`. This is useful for constructing your own email link in the email template. | +| `{{ .SiteURL }}` | Contains your application's Site URL. This can be configured in your project's [authentication settings](https://supabase.com/dashboard/project/_/auth/url-configuration). | +| `{{ .Email }}` | Contains the user's email address. | +| `{{ .NewEmail }}` | Contains the new user's email address. | From 151be0f79a0744bf0997ab059cef05e5517ff195 Mon Sep 17 00:00:00 2001 From: Copple <10214025+kiwicopple@users.noreply.github.com> Date: Tue, 15 Aug 2023 15:35:46 +0200 Subject: [PATCH 05/10] small updates --- .../cli/customizing-email-templates.mdx | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index 0de1dd95101..5c3029b0366 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -4,15 +4,14 @@ export const meta = { id: 'customizing-email-templates', title: 'Customizing email templates', description: 'Customizing local email templates using config.toml.', + subtitle: 'Customizing local email templates using config.toml.', } -The Supabase CLI uses a `config.toml` file to manage local configuration. This file is located in the `supabase` directory of your project. +You can customize the email templates for local development [using the `config.toml` settings](/docs/guides/cli/managing-config). -## Config reference +## Auth Templates -The `config.toml` file is automatically created when you run `supabase start`. - -There are a wide variety of options available, which can be found in the [CLI Config Reference](/docs/reference/cli/config). +There are several Auth templates which can be configured, detailed in the [CLI Config Reference](/docs/guides/cli/config#auth-config). For example, to update the "Invite" email subject and content for local development, you can append the following information to `config.toml`: @@ -24,12 +23,6 @@ content_path = "./supabase/auth/email/invite.html" The `content_path` should contain the html file you are pointing to otherwise the CLI won't start the project. - - -These settings are only for local development, if you want to use the same content for your hosted Supabase instance you will need to copy and paste these into the Supabase Dashboard - - - ### Email template variables The templating system provides the following variables for use: @@ -49,6 +42,10 @@ The templating system provides the following variables for use: +## Deploying email templates + +These settings are only for local development. To update your hosted project, please copy the templates into the [Email Templates](/dashboard/project/_/auth/templates) section of the Dashboard. + export const Page = ({ children }) => export default Page From 722817d637c86ad0c6080804ccd97a0b9279b5f6 Mon Sep 17 00:00:00 2001 From: Copple <10214025+kiwicopple@users.noreply.github.com> Date: Tue, 15 Aug 2023 16:03:40 +0200 Subject: [PATCH 06/10] restructures the doc --- .../cli/customizing-email-templates.mdx | 106 ++++++++++++++---- 1 file changed, 87 insertions(+), 19 deletions(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index 5c3029b0366..50feb9b9165 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -7,40 +7,108 @@ export const meta = { subtitle: 'Customizing local email templates using config.toml.', } -You can customize the email templates for local development [using the `config.toml` settings](/docs/guides/cli/managing-config). +You can customize the email templates for local development [using the `config.toml` settings](/docs/guides/cli/config#auth-config). -## Auth Templates +## Configuring Templates -There are several Auth templates which can be configured, detailed in the [CLI Config Reference](/docs/guides/cli/config#auth-config). +You should provide a relative URL to the `content_path` parameter, pointing to an HTML file which contains the template. For example -For example, to update the "Invite" email subject and content for local development, you can append the following information to `config.toml`: + -```toml +```toml supabase/config.toml [auth.email.template.invite] subject = "You are invited to Acme Inc" -content_path = "./supabase/auth/email/invite.html" +content_path = "./supabase/templates/invite.html" ``` -The `content_path` should contain the html file you are pointing to otherwise the CLI won't start the project. +```html supabase/templates/invite.html + + +

Confirm your signup

+

Confirm your mail

+ + +``` -### Email template variables + + +## Available email templates + +There are several Auth email templates which can be configured: + +- `auth.email.template.invite` +- `auth.email.template.confirmation` +- `auth.email.template.recovery` +- `auth.email.template.magic_link` +- `auth.email.template.email_change` + +## Template variables The templating system provides the following variables for use: -| Name | Description | -| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `{{ .ConfirmationURL }}` | Contains the confirmation URL. For example, a signup confirmation URL would look like: `https://project-ref.supabase.co/auth/v1/verify?token={{ .TokenHash }}&type=signup&redirect_to=https://example.com/path` . | -| `{{ .Token }}` | Contains a 6-digit One-Time-Password (OTP) that can be used instead of the `{{. ConfirmationURL }}` . | -| `{{ .TokenHash }}` | Contains a hashed version of the `{{ .Token }}`. This is useful for constructing your own email link in the email template. | -| `{{ .SiteURL }}` | Contains your application's Site URL. This can be configured in your project's [authentication settings](https://supabase.com/dashboard/project/_/auth/url-configuration). | -| `{{ .Email }}` | Contains the user's email address. | -| `{{ .NewEmail }}` | Contains the new user's email address. | +### ConfirmationURL - +Contains the confirmation URL. For example, a signup confirmation URL would look like: -`{{ .NewEmail }}` is only available in the email_change email template +``` +https://project-ref.supabase.co/auth/v1/verify?token={{ .TokenHash }}&type=signup&redirect_to=https://example.com/path +``` - +**Usage** + +```html +

Click here to confirm: {{ .ConfirmationURL }}

+``` + +### Token + +Contains a 6-digit One-Time-Password (OTP) that can be used instead of the `ConfirmationURL`. + +**Usage** + +```html +

Here is your one time password: {{ .Token }}

+``` + +### TokenHash + +Contains a hashed version of the `Token`. This is useful for constructing your own email link in the email template. + +**Usage** + +```html +

Click here to confirm your login.

+``` + +### SiteURL + +Contains your application's Site URL. This can be configured in your project's [authentication settings](/dashboard/project/_/auth/url-configuration). + +**Usage** + +```html +

Visit here to log in.

+``` + +### Email + +Contains the user's email address. + +**Usage** + +```html +

A recovery request was sent to {{ .Email }}.

+``` + +### NewEmail + +Contains the new user's email address. This is only available in the `email_change` email template. + +**Usage** + +```html +

You are requesting to update your email address to {{ .NewEmail }}.

+``` ## Deploying email templates From de3ac59b52724daee322fab0652ccc4f61ec05b5 Mon Sep 17 00:00:00 2001 From: Copple <10214025+kiwicopple@users.noreply.github.com> Date: Tue, 15 Aug 2023 16:05:22 +0200 Subject: [PATCH 07/10] updates all config links --- apps/docs/components/CustomHTMLElements/Heading.tsx | 2 +- .../components/Navigation/NavigationMenu/NavigationMenu.tsx | 2 +- apps/docs/data/nav/supabase-cli.ts | 2 +- apps/docs/pages/guides/cli/managing-config.mdx | 2 +- apps/docs/pages/guides/functions/cicd-workflow.mdx | 2 +- apps/docs/pages/guides/functions/examples/github-actions.mdx | 2 +- apps/docs/pages/guides/functions/quickstart.mdx | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/apps/docs/components/CustomHTMLElements/Heading.tsx b/apps/docs/components/CustomHTMLElements/Heading.tsx index 9d427e79b99..336dba4d0f7 100644 --- a/apps/docs/components/CustomHTMLElements/Heading.tsx +++ b/apps/docs/components/CustomHTMLElements/Heading.tsx @@ -26,7 +26,7 @@ interface Props { * * In tsx files, we can generate this tocList directly. For these files, we don't * need to parse the and generate anchors. Custom anchors are used in tsx files. - * (see: /pages/reference/cli/config.tsx) + * (see: /pages/guides/cli/config.tsx) */ const Heading: React.FC = ({ tag, customAnchor, children }) => { const HeadingTag = `${tag}` as any diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx index 452eb693116..bb5b6035dbd 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.tsx @@ -95,7 +95,7 @@ const menus: Menu[] = [ }, { id: 'supabase_cli', - // TODO: Add path '/reference/cli/config' + // TODO: Add path '/guides/cli/config' path: '/guides/cli', type: 'guide', }, diff --git a/apps/docs/data/nav/supabase-cli.ts b/apps/docs/data/nav/supabase-cli.ts index 65a5bce9419..9eb1a91e66c 100644 --- a/apps/docs/data/nav/supabase-cli.ts +++ b/apps/docs/data/nav/supabase-cli.ts @@ -4,7 +4,7 @@ const Nav = [ items: [ { name: 'Supabase CLI', url: '/reference/cli', items: [] }, { name: 'Usage', url: '/reference/cli/usage', items: [] }, - { name: 'Configuration', url: '/reference/cli/config', items: [] }, + { name: 'Configuration', url: '/guides/cli/config', items: [] }, { name: 'Release Notes', url: '/reference/cli/release-notes', items: [] }, ], }, diff --git a/apps/docs/pages/guides/cli/managing-config.mdx b/apps/docs/pages/guides/cli/managing-config.mdx index 1f93c9e52cf..d63eeafd81c 100644 --- a/apps/docs/pages/guides/cli/managing-config.mdx +++ b/apps/docs/pages/guides/cli/managing-config.mdx @@ -12,7 +12,7 @@ The Supabase CLI uses a `config.toml` file to manage local configuration. This f The `config.toml` file is automatically created when you run `supabase start`. -There are a wide variety of options available, which can be found in the [CLI Config Reference](/docs/reference/cli/config). +There are a wide variety of options available, which can be found in the [CLI Config Reference](/docs/guides/cli/config). For example, to enable the "Apple" OAuth provider for local development, you can append the following information to `config.toml`: diff --git a/apps/docs/pages/guides/functions/cicd-workflow.mdx b/apps/docs/pages/guides/functions/cicd-workflow.mdx index 4827bde8473..b729044c17e 100644 --- a/apps/docs/pages/guides/functions/cicd-workflow.mdx +++ b/apps/docs/pages/guides/functions/cicd-workflow.mdx @@ -38,7 +38,7 @@ jobs: Since Supabase CLI [v1.62.0](https://github.com/supabase/cli/releases/tag/v1.62.0) you can deploy all functions with a single command. -Individual function configuration like [JWT verification](/docs/reference/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/reference/cli/config#functions.function_name.import_map) can be set via the `config.toml` file. +Individual function configuration like [JWT verification](/docs/guides/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/guides/cli/config#functions.function_name.import_map) can be set via the `config.toml` file. ```toml [functions.hello-world] diff --git a/apps/docs/pages/guides/functions/examples/github-actions.mdx b/apps/docs/pages/guides/functions/examples/github-actions.mdx index 7baf600b40d..d29fd6f1981 100644 --- a/apps/docs/pages/guides/functions/examples/github-actions.mdx +++ b/apps/docs/pages/guides/functions/examples/github-actions.mdx @@ -47,7 +47,7 @@ jobs: Since Supabase CLI [v1.62.0](https://github.com/supabase/cli/releases/tag/v1.62.0) you can deploy all functions with a single command. -Individual function configuration like [JWT verification](/docs/reference/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/reference/cli/config#functions.function_name.import_map) can be set via the `config.toml` file. +Individual function configuration like [JWT verification](/docs/guides/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/guides/cli/config#functions.function_name.import_map) can be set via the `config.toml` file. ```toml [functions.hello-world] diff --git a/apps/docs/pages/guides/functions/quickstart.mdx b/apps/docs/pages/guides/functions/quickstart.mdx index 14de4f79620..7c32c36db06 100644 --- a/apps/docs/pages/guides/functions/quickstart.mdx +++ b/apps/docs/pages/guides/functions/quickstart.mdx @@ -66,7 +66,7 @@ supabase functions deploy Since Supabase CLI [v1.62.0](https://github.com/supabase/cli/releases/tag/v1.62.0) you can deploy all functions with a single command. This is useful for example when [deploying with GitHub Actions](/docs/guides/functions/cicd-workflow). -Individual function configuration like [JWT verification](/docs/reference/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/reference/cli/config#functions.function_name.import_map) can be set via the `config.toml` file. +Individual function configuration like [JWT verification](/docs/guides/cli/config#functions.function_name.verify_jwt) and [import map location](/docs/guides/cli/config#functions.function_name.import_map) can be set via the `config.toml` file. ```toml [functions.hello-world] From 3c6dd9d7d0a5ab67b34f82314daca2a92b06e177 Mon Sep 17 00:00:00 2001 From: Copple <10214025+kiwicopple@users.noreply.github.com> Date: Tue, 15 Aug 2023 16:21:57 +0200 Subject: [PATCH 08/10] updates the example --- apps/docs/pages/guides/cli/customizing-email-templates.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index 50feb9b9165..be776360b4b 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -77,7 +77,10 @@ Contains a hashed version of the `Token`. This is useful for constructing your o **Usage** ```html -

Click here to confirm your login.

+

Follow this link to confirm your user:

+

+ Confirm your mail +

``` ### SiteURL From 36d1e792a5bfa45d197880c2f4f296ece04d1fde Mon Sep 17 00:00:00 2001 From: Andrew Smith Date: Tue, 15 Aug 2023 14:30:25 +0000 Subject: [PATCH 09/10] fix small typo --- apps/docs/pages/guides/cli/customizing-email-templates.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index be776360b4b..91396f2b3fd 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -79,7 +79,9 @@ Contains a hashed version of the `Token`. This is useful for constructing your o ```html

Follow this link to confirm your user:

- Confirm your mail + Confirm your email

``` From efac10f76d27e0c0ed4505ccd5b3a2e4027bac0f Mon Sep 17 00:00:00 2001 From: Andrew Smith Date: Tue, 15 Aug 2023 14:31:58 +0000 Subject: [PATCH 10/10] Another small typo --- apps/docs/pages/guides/cli/customizing-email-templates.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/pages/guides/cli/customizing-email-templates.mdx b/apps/docs/pages/guides/cli/customizing-email-templates.mdx index 91396f2b3fd..4702b09ad72 100644 --- a/apps/docs/pages/guides/cli/customizing-email-templates.mdx +++ b/apps/docs/pages/guides/cli/customizing-email-templates.mdx @@ -25,7 +25,7 @@ content_path = "./supabase/templates/invite.html"

Confirm your signup

-

Confirm your mail

+

Confirm your email

```