Import and Export Between Environments
Form import and export moves form structure and settings between environments. It does not include submission data. Use it when staging a new form for production, cloning a client's enquiry form to another project, or backing up structure before a major edit.
Prerequisites
- Import & Export
- Access to Formie → Settings → Import/Export on both environments
What Export Includes
Exporting a form produces a JSON file containing:
- Form details and settings
- Pages and fields, including synced field settings and relationships
- Email notifications
- Form template assignment
- Email template assignment
- PDF template assignment
It is a structural snapshot — not a dump of submissions.
What Export Does Not Include
- Submissions
- Integration OAuth tokens (reconnect integrations per environment)
- Spam settings and captcha secrets (see Project config, environment, and control panel settings)
Export Workflow
- On the source environment, open Formie → Settings → Import/Export
- Select the form(s) to export
- Download the JSON file
- Commit to version control if your team tracks form structure in git (optional)
For multiple forms, export one at a time or automate via console commands if your deployment pipeline supports it.
Import Workflow
- On the target environment, open Formie → Settings → Import/Export
- Upload the JSON file
- Review the preview — Formie validates the file format
- Choose how to handle handle collisions:
| Option | When to use |
|---|---|
| Create new form | Production already has a different form with the same handle; import generates a unique handle (e.g. contactForm1) |
| Update existing form | Staging → production promotion where handles match and you intend a full overwrite |
Updating an existing form is a full overwrite of structure — fields, notifications, and template assignments. Submissions remain, but field handles that changed can orphan old submission data. Take a backup or export first.
- Check any synced fields in the list. Formie creates missing synced fields and links matching ones automatically. If a synced field’s settings differ, the review lists the forms using it and asks whether to keep this site’s settings or update the synced field.
- Complete the import and verify in the form builder
Formie only supports its own export format. Arbitrary JSON will not import.
Environment Promotion Patterns
Staging → Production (Same Project)
- Build and test the form on staging
- Export JSON
- Import on production with Update existing form if handles match
- Re-test notifications, integrations, and captchas on production URLs
- Run
project-config/syncif the import touched project-scoped resources
Promoting Forms That Share a Field
Suppose your local Contact and Quote forms share an Email Address field. Export both forms, then import Contact on production. Formie creates the synced Email Address field if it is missing. Import Quote, and it links to that field automatically. You can also import Quote first; the order does not matter.
If production already has that synced field with different settings, Keep this site’s settings leaves its settings and translations intact. To deploy a change to the shared field itself, choose Update synced field and review the listed forms: they all receive that change, even if you are only importing one form. You must be able to manage every affected form.
After importing, open both forms and confirm the field is marked as synced. Check that the field has the intended Required state in each form, then submit a test entry through each form.
The same name or handle does not establish a relationship. Formie uses the synced field’s unique identifier (UID) from the export. For forms previously imported without their relationships, see Updating previously imported forms.
Client Template → New Project
- Export the forms you want to reuse from your starter Craft install
- Import on the client site as Create new form. Synced fields stay synced, so detach them in the form builder before exporting if the new forms shouldn’t share them
- Rename handles to client conventions
- Assign form groups and site policies for the client's multi-site setup
Disaster Recovery Before a Big Edit
Export the current form JSON before deleting fields or restructuring. Re-import if the edit goes wrong.
Combine with Project Config
Some Formie resources travel via project config instead of import/export:
| Resource | Mechanism |
|---|---|
| Form groups | formie.formGroups in project config |
| Project stencils | formie.stencils in project config |
| Submission statuses | formie.statuses |
Use import/export for individual form snapshots. Use project config for team-wide defaults and stencils that should version with code.
See Stencils for repeatable form types.
Post-Import Checklist
- Field handles unchanged (or migration plan for submission data)
- Email notifications send from correct domain on target environment
- Integrations reconnected with production credentials
- Captcha keys set under Spam Protection
- Form enabled on expected sites (form group site policy)
- Front-end template or headless app points at correct form handle
- Test submit on production