vault backup: 2026-05-15 15:27:05

wiki/_master-index.md

@@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
 | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 |
 | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 |
 | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 |
-| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 68 |
+| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 69 |
 
 | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 |
 | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 |

wiki/payloadcms/_index.md

@@ -69,3 +69,4 @@
 | [[wiki/payloadcms/fields-code\|Code Field]] | Monaco editor UI (VS Code engine) storing a plain string — language syntax highlighting, editorOptions, custom components | raw/fields__code.md | 2026-05-15 |
 | [[wiki/payloadcms/fields-collapsible\|Collapsible Field]] | Presentational-only layout field — groups nested fields under a collapsible header; no DB column; supports dynamic label via `({ data, path })` | raw/fields__collapsible.md | 2026-05-15 |
 | [[wiki/payloadcms/fields-date\|Date Field]] | Date picker field — ISO 8601 storage, pickerAppearance modes, timezone support with separate `_tz` column, custom UTC offsets, GraphQL enum names | raw/fields__date.md | 2026-05-15 |
+| [[wiki/payloadcms/fields-email\|Email Field]] | Email field with built-in format validation — unique index, saveToJWT, index, placeholder, autoComplete, custom components | raw/fields__email.md | 2026-05-15 |

wiki/payloadcms/fields-email.md

@@ -0,0 +1,152 @@
+---
+title: "Email Field"
+aliases: [payload-email-field, email-field-payloadcms]
+tags: [payloadcms, fields, email, validation]
+sources: [raw/fields__email.md]
+created: 2026-05-15
+updated: 2026-05-15
+---
+
+## Overview
+
+The Email field enforces that the stored value is a valid email address. It renders a standard email input in the Admin Panel with built-in format validation on both client and server.
+
+```ts
+import type { Field } from 'payload'
+
+export const MyEmailField: Field = {
+  name: 'contact',
+  type: 'email',
+}
+```
+
+## Key Takeaways
+
+- `type: 'email'` — built-in email format validation, no custom validator needed for basic use
+- Inherits all base field options: `required`, `unique`, `index`, `localized`, `hidden`, `defaultValue`, `hooks`, `access`, `saveToJWT`, `virtual`
+- `unique: true` creates a **database-level unique index** on the field path
+- `index: true` — add if you query by email frequently (e.g. user lookup)
+- `saveToJWT: true` — embeds email into JWT/cookie; useful for reading email in access control without a DB round-trip (see [[wiki/payloadcms/authentication-token-data|Token Data]])
+- `virtual: true` — field is not persisted to DB; use for computed or derived email values
+
+## Config Options
+
+| Option | Description |
+|--------|-------------|
+| `name` * | DB property name |
+| `label` | Admin panel label (string or per-locale object) |
+| `unique` | DB-level unique index |
+| `index` | Query performance index |
+| `validate` | Custom validation function (client + server) |
+| `saveToJWT` | Include in user JWT token |
+| `hooks` | Field lifecycle hooks |
+| `access` | Field-level access control |
+| `hidden` | Exclude from API and admin UI (still stored in DB) |
+| `defaultValue` | Default email value |
+| `localized` | Enable per-locale storage (requires global localization config) |
+| `required` | Make field mandatory |
+| `admin` | Admin UI options (see below) |
+| `virtual` | Skip DB persistence; or path string to link to a relationship |
+
+## Admin Options
+
+```ts
+admin: {
+  placeholder: 'user@example.com',
+  autoComplete: 'email',
+}
+```
+
+| Property | Description |
+|----------|-------------|
+| `placeholder` | Placeholder string shown in the input |
+| `autoComplete` | Browser autocomplete attribute value |
+
+Plus all standard [[wiki/payloadcms/fields-basic|base field admin options]].
+
+## Example — Full Config
+
+```ts
+import type { CollectionConfig } from 'payload'
+
+export const Contacts: CollectionConfig = {
+  slug: 'contacts',
+  fields: [
+    {
+      name: 'contact',
+      type: 'email',
+      label: 'Contact Email Address',
+      required: true,
+      unique: true,
+      index: true,
+      saveToJWT: false,
+      admin: {
+        placeholder: 'user@example.com',
+        autoComplete: 'email',
+      },
+    },
+  ],
+}
+```
+
+## Custom Components
+
+### Field — Server
+
+```tsx
+import type { EmailFieldServerComponent } from 'payload'
+import { EmailField } from '@payloadcms/ui'
+
+export const CustomEmailFieldServer: EmailFieldServerComponent = ({
+  clientField, path, schemaPath, permissions,
+}) => (
+  <EmailField field={clientField} path={path} schemaPath={schemaPath} permissions={permissions} />
+)
+```
+
+### Field — Client
+
+```tsx
+'use client'
+import type { EmailFieldClientComponent } from 'payload'
+import { EmailField } from '@payloadcms/ui'
+
+export const CustomEmailFieldClient: EmailFieldClientComponent = (props) => (
+  <EmailField {...props} />
+)
+```
+
+### Label — Server
+
+```tsx
+import type { EmailFieldLabelServerComponent } from 'payload'
+import { FieldLabel } from '@payloadcms/ui'
+
+export const CustomEmailFieldLabelServer: EmailFieldLabelServerComponent = ({ clientField, path }) => (
+  <FieldLabel label={clientField?.label || clientField?.name} path={path} required={clientField?.required} />
+)
+```
+
+### Label — Client
+
+```tsx
+'use client'
+import type { EmailFieldLabelClientComponent } from 'payload'
+import { FieldLabel } from '@payloadcms/ui'
+
+export const CustomEmailFieldLabelClient: EmailFieldLabelClientComponent = ({ field, path }) => (
+  <FieldLabel label={field?.label || field?.name} path={path} required={field?.required} />
+)
+```
+
+## Related
+
+- [[wiki/payloadcms/fields-basic|Fields: Basic]] — all scalar field types overview
+- [[wiki/payloadcms/authentication-token-data|Authentication — Token Data]] — use `saveToJWT` to embed email into JWT
+- [[wiki/payloadcms/database-indexes|Database Indexes]] — `unique` and `index` internals
+- [[wiki/payloadcms/authentication-overview|Authentication Overview]] — Users collection with email auth
+- [[wiki/payloadcms/custom-components-authoring|Custom Components Authoring]] — RSC vs Client component rules
+
+---
+
+*Source: raw/fields__email.md — https://payloadcms.com/docs/fields/email*