Add a settings page

A settings page is a tab in /admin/settings. You add a page file and a registry entry.

Step 1: write the page

Make the file app/pages/admin/settings/reports.vue.

<script setup lang="ts">
const { t } = usePlutoI18n()

useHead({ title: () => t('my-layer.settings.reports') })
</script>

<template>
  <!-- Core renders the toolbar, the tabs and the frame of the page. -->
  <div class="flex flex-col gap-y-6 lg:gap-y-8">
    <UCard>
      <template #header>
        <h2 class="font-semibold">Weekly report</h2>
        <p class="text-muted text-sm">The email that the team gets each Monday.</p>
      </template>
    </UCard>
  </div>
</template>

Do not repeat the name of the tab as a heading: the tab shows it. Put each part of the page in a UCard, like the other tabs.

Every page needs a title. Use a getter in useHead, so a language switch updates the title.

Step 2: register the tab

definePlutoExtension({
  id: 'my-layer',
  settingsPages: [
    {
      id: 'reports',
      order: 30,
      label: 'my-layer.settings.reports',
      icon: 'lucide:chart-bar',
      to: '/admin/settings/reports',
      capability: 'reports:read'
    }
  ]
})

• Use capability: '*' for an admin-only tab.
• Without a capability, every user in the admin sees the tab.
• The order of General is 0.

Step 3: check on the server

The tab check hides the tab. It does not protect your data. The routes that the page calls must check the capability. For Supabase, use requireCapability. See Users and roles.

Optional: a panel on the General tab

For a small form, register a settingsPanels entry instead of a page. Core renders it on the General tab. A settings driver stores the values. Namespace the keys, for example my-layer.page_size.

Optional: a section on the Email page

Register a mailPanels entry to add a section to Settings, Email. See Mail.

What you get for free

• The tabs show when 2 or more pages are visible.
• The sidebar Settings item gets one child for each visible page.
• The command palette gets a "Go to" command for the page.
• Core shows a no-permission alert instead of the page when the user lacks the capability.

See Settings pages.