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: 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: Choose a cache backend through CACHE_URL, keep sessions readable across worker processes, and verify the result.
• Local HTTPS Development: Set up mkcert, gunicorn TLS, and Vite HTTPS for a production-like local environment with secure cookies.

Coding Agents

• Use VUEDA with Coding Agents: 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: Optional chart palette and mappings for VUEDA typography, surfaces, and dark mode.

• Client Plugin Prerequisites: Vue plugins, directives, and VUEDA-specific setup functions that must be registered before mounting.

• shadcn-vue and VUEDA: 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: Concrete recipes for the four customization scopes: instance, component, family, and brand.

• Place the Page Title and Page Actions: 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: Minimal server/client pieces for list/read/create/update/delete/list.
• Set Up CRUDL for a Composite Primary Key Model: Set up serializer, viewset, and filterset for models that use a composite primary key.
• Data That VUEDA Does Not Display: 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: Give a proxy model its own serializer, viewset, permissions, and model-info registration without a separate database table.
• Split Read/Write Serializers Safely: Use viewset serializer switching without breaking model-info metadata.
• Lock Fields to Specific Write Actions: Use ExcludeFieldsSerializerMixin to make fields read-only on create or update without a full serializer split.
• Configure list/read/create/update Views: Tune model config per view, including default fields/expands/actions.
• Link List Rows to Read and Update Views: Add a per-row link from a list view to that row's read or update view.
• Open a Scoped List: Narrow a list view through a hidden-filter link or a declared params scope, and let the reader clear it.
• Customize List Column Rendering: Override how list columns render with type-aware column adapters, model config, view props, or slots.
• Expose Aggregates in list Responses: Use server column totals and render them in list views.

Fields, Forms, and Relationships

• Model Choices, Lookup Fields, and Dynamic Options: Use model-info choices and choice endpoints correctly.
• Use Expand and Sparse Field Controls: Control payload shape with expand and fields.
• Customize Model Info Field and Expand Metadata: Correct generated model_fields/model_expands metadata for SerializerMethodFields with get_field_model_info and get_expand_model_info.
• Build Nested/Inlined Writes: Handle writable nested relations and server validation behavior.
• Render a Relation as an Inline: 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: Override field/widget components and props in model config.
• Handle Form Validation and Server Errors: Map server validation responses into VUEDA form context.

Actions, Permissions, and Workflow

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

Model History

• Purge Model History Rows: Delete event rows past their retention window through the append-only trigger.

Async Work and Integrations

• Run Actions in the VUEDA Dispatch Queue (VDQ): Queue long-running work and report status.
• Send Email from VDQ with Anymail: Configure queue item email workflows and attachments.
• Send SMS from VDQ with Twilio: Configure SMS sender/receiver flow and retry semantics.