---
url: "https://vueda.dev/v3/guides/index.md"
title: "Guides"
---

# Guides

Guides are task-focused how-tos for integrators. They assume you know your domain model and want concrete steps for wiring server and client behavior.

## Upgrading

- [Upgrade from VUEDA v2](/v3/guides/upgrade-from-v2.md): Move a project from server v2.3.3 and client v2.0.4 to the v3 beta, and assess the v2 security defects that v3 fixes.

## Environment & Networking

- [Configure the Cache and Sessions](/v3/guides/configure-cache-and-sessions.md): Choose a cache backend through `CACHE_URL`, keep sessions readable across worker processes, and verify the result.
- [Local HTTPS Development](/v3/guides/local-https-setup.md): Set up mkcert, gunicorn TLS, and Vite HTTPS for a production-like local environment with secure cookies.

## Coding Agents

- [Use VUEDA with Coding Agents](/v3/guides/use-coding-agents.md): Install the integrator skill for Codex or Claude Code and use the documentation for your application's VUEDA major version.

## Client Setup & Theming

- [Style Unovis Charts](/v3/guides/style-unovis-charts.md): Optional chart palette and mappings for VUEDA typography, surfaces, and dark mode.

- [Client Plugin Prerequisites](/v3/guides/client-plugin-prerequisites.md): Vue plugins, directives, and VUEDA-specific setup functions that must be registered before mounting.
- [shadcn-vue and VUEDA](/v3/guides/shadcn-vue.md): How VUEDA relates to shadcn-vue, what `shadcn-vue add` does and does not support, and how to use shadcn-vue blocks alongside VUEDA.
- [Customize VUEDA Appearance](/v3/guides/customize-vueda-appearance.md): Concrete recipes for the four customization scopes: instance, component, family, and brand.
- [Place the Page Title and Page Actions](/v3/guides/place-page-title-and-actions.md): Establish the `usePageTitle` context in your layout, contribute titles from views, render page actions, and build a custom title display.

## Resource Modeling & CRUDL

- [Create a CRUDL Surface for a New Model](/v3/guides/create-crudl-surface.md): Minimal server/client pieces for `list`/`read`/`create`/`update`/`delete`/`list`.
- [Set Up CRUDL for a Composite Primary Key Model](/v3/guides/composite-primary-keys.md): Set up serializer, viewset, and filterset for models that use a composite primary key.
- [Data That VUEDA Does Not Display](/v3/guides/data-vueda-does-not-display.md): Use a plain Django model or an opted-out manager for exports, imports, and API data, and see which VUEDA pieces bring `formatted_name` checks.
- [Expose a Proxy Model as a Separate CRUDL Surface](/v3/guides/proxy-models.md): Give a proxy model its own serializer, viewset, permissions, and model-info registration without a separate database table.
- [Split Read/Write Serializers Safely](/v3/guides/split-read-write-serializers.md): Use viewset serializer switching without breaking model-info metadata.
- [Lock Fields to Specific Write Actions](/v3/guides/hide-fields-per-write-action.md): Use `ExcludeFieldsSerializerMixin` to make fields read-only on `create` or `update` without a full serializer split.
- [Configure `list`/`read`/`create`/`update` Views](/v3/guides/configure-crud-views.md): Tune model config per view, including default fields/expands/actions.
- [Link List Rows to Read and Update Views](/v3/guides/link-list-rows-to-detail-views.md): Add a per-row link from a `list` view to that row's `read` or `update` view.
- [Open a Scoped List](/v3/guides/scope-a-list.md): Narrow a `list` view through a hidden-filter link or a declared `params` scope, and let the reader clear it.
- [Customize List Column Rendering](/v3/guides/customize-list-column-rendering.md): Override how `list` columns render with type-aware column adapters, model config, view props, or slots.
- [Expose Aggregates in `list` Responses](/v3/guides/list-column-totals.md): Use server column totals and render them in `list` views.

## Fields, Forms, and Relationships

- [Model Choices, Lookup Fields, and Dynamic Options](/v3/guides/choices-and-lookups.md): Use model-info choices and choice endpoints correctly.
- [Use Expand and Sparse Field Controls](/v3/guides/expand-and-fields-controls.md): Control payload shape with `expand` and `fields`.
- [Customize Model Info Field and Expand Metadata](/v3/guides/customize-model-info-metadata.md): Correct generated `model_fields`/`model_expands` metadata for `SerializerMethodField`s with `get_field_model_info` and `get_expand_model_info`.
- [Build Nested/Inlined Writes](/v3/guides/nested-writable-inlines.md): Handle writable nested relations and server validation behavior.
- [Render a Relation as an Inline](/v3/guides/render-relations-as-inlines.md): Show a relation as a stacked or tabular inline on create, update, and read forms, and choose the fields in each row.
- [Customize Field and Widget Rendering](/v3/guides/custom-field-widget-rendering.md): Override field/widget components and props in model config.
- [Handle Form Validation and Server Errors](/v3/guides/form-validation-and-errors.md): Map server validation responses into VUEDA form context.

## Actions, Permissions, and Workflow

- [Control Action Availability in the UI](/v3/guides/control-action-availability.md): Combine server action metadata, groups, and client filtering.
- [Implement Row-Level Permissions](/v3/guides/implement-row-level-permissions.md): Add queryset/object checks and verify `list` filtering behavior.
- [Map Django and VUEDA Permission Names](/v3/guides/permission-name-mapping.md): Configure and verify `PERMISSION_NAMES_MAPPING`.
- [Add Workflow State and Transition Permissions](/v3/guides/workflow-state-permissions.md): Layer state-based grants/denies over [CRUDL](/v3/reference/glossary.md#crudl) permissions.
- [Design Transition UX and Redirects](/v3/guides/transition-ux-and-redirects.md): Integrate transitions with action routing and post-submit redirects.
- [Manage Workflows and Generate Workflow Migrations](/v3/guides/manage-workflows.md): Create, edit, and delete workflows through the UI, then capture those changes as a replayable migration.
- [Manage Groups and Generate Group Migrations](/v3/guides/manage-groups.md): Add, rename, and remove groups through the permission overview UI, then capture those changes as a replayable migration.
- [Use the Permissions and Workflow Overview](/v3/guides/permissions-workflow-overview.md): Audit group and permission assignments across all registered models, and inspect what a specific user can access.

## Model History

- [Purge Model History Rows](/v3/guides/purge-model-history.md): Delete event rows past their retention window through the append-only trigger.

## Async Work and Integrations

- [Run Actions in the VUEDA Dispatch Queue (VDQ)](/v3/guides/vdq-actions.md): Queue long-running work and report status.
- [Send Email from VDQ with Anymail](/v3/guides/vdq-email-anymail.md): Configure queue item email workflows and attachments.
- [Send SMS from VDQ with Twilio](/v3/guides/vdq-sms-twilio.md): Configure SMS sender/receiver flow and retry semantics.