alpha
Supabase

Supabase layer

Use Supabase as the backend of Pluto. Install the layer and run the setup.

@plutocms/supabase is the backend layer for Supabase. It gives Pluto a database, sign-in, users, roles, and database migrations.

What the layer gives

  • An auth driver for the admin shell. See Auth.
  • Versioned database migrations that an admin applies from the admin UI. See Migrations.
  • Roles and capabilities in the database, and server guards. See Users and roles.
  • A content adapter for the generic content routes. See Content adapter.
  • A stored admin language for each user. See Profile language.
  • Admin pages in English and Brazilian Portuguese.

Install

You need a Supabase project. You need the project URL and the publishable key. Find them in the Supabase dashboard.

Set the environment variables

Add these variables to the .env file in the root of your project:

.env
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-publishable-supabase-key

Install and extend the layer

Install the package first. extends does not install it.

npm install @plutocms/supabase

Then add the layer to extends in nuxt.config.ts.

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@plutocms/supabase']
})

The layer extends @plutocms/core itself. Do not add it to extends. The layer also brings @nuxtjs/supabase and the supabase CLI as its own dependencies. The create-pluto CLI does these steps for you.

If you use a feature layer, extend only that layer. @plutocms/supabase-shop and @plutocms/supabase-blog already extend this layer. See Layers.

First run

On a new install, the setup guard sends every admin path to /admin/setup. The setup wizard has two steps: Database Setup and Complete Setup.

  1. The wizard asks for the database connection string and the database password. The wizard puts the password in the [YOUR-PASSWORD] placeholder of the string. The server opens a direct PostgreSQL connection and runs the migration files of the layers.
  2. As the last step, the server writes the connection string to .env as DATABASE_URL. The server does not store the password.
  3. When the setup is done, the wizard tells you to create your admin account by signing up.
In development, Nuxt restarts the dev server when .env changes. The page can briefly show a reconnecting message. This is expected, not an error.

After the setup is done, /admin/setup redirects to /admin/login.

When DATABASE_URL is set, the server also applies the pending migrations of every layer at start-up. In development, it then regenerates shared/types/supabase.ts from the live schema. See Migrations.

API routes

The layer includes API routes for Supabase services. All of them are under /api/_pluto/supabase:

  • GET /api/_pluto/supabase/settings
  • PUT /api/_pluto/supabase/settings. It needs the settings:manage capability. A failed save is an HTTP error with the key supabase.errors.settingsSave.
  • GET /api/_pluto/supabase/setup and POST /api/_pluto/supabase/setup. They serve the setup wizard. A failed setup is an HTTP error with the key supabase.errors.setupFailed.
  • POST /api/_pluto/supabase/auth/signup. A failed sign-up is an HTTP error with the key supabase.errors.signupFailed.
  • The access API under /api/_pluto/supabase/access/**. See Users and roles.
  • GET and PUT /api/_pluto/supabase/me/locale. See Profile language.
  • GET /api/_pluto/supabase/me/capabilities.
  • GET /api/_pluto/supabase/migrations and POST /api/_pluto/supabase/migrations/run. See Migrations.
These routes are internal. They are for the admin. They are not a stable contract. Core blocks a cross-site write to /api/_pluto/**. A public site reads content through the public API of Pluto. See Public API.

The content adapter applies filter[field] (equality) and puts the created, updated, and published-at timestamps on items. For a public read, it uses an anonymous client. There is no session, and it never uses the service role key. The public API gives the same answer to everyone. See Content adapter.

Composables

  • useAuth. It signs in, requests a password reset, and updates the password with Supabase.

Types

  • Database. Auto-imported type definitions for Supabase database interactions. In development, the layer regenerates the types file after it applies a migration.

Settings

The layer stores settings in the settings table with free-text, namespaced keys, for example blog.posts_per_page. The General panel of the settings has website_title, website_description, and website_url. Two of them feed the shell: website_title and website_url.

Security

Sessions, CSRF checks, rate limits, and the HTML sanitizer of the Git CMS.

Migrations

Apply versioned database migrations from the admin UI.