Category: Tutorials

One of the biggest challenges with headless WordPress is preview functionality. Editors want to see their drafts before publishing, but your static site only shows published content.

FlatWP’s preview mode solves this elegantly.

How It Works

When an editor clicks “Preview” in WordPress, our plugin generates a special URL:

https://flatwp.com/api/preview?secret=xyz&id=123&type=post

This hits your Next.js preview API route, which:

1. Verifies the secret token
2. Enables Next.js draft mode via cookies
3. Redirects to the post URL

Now when Next.js renders the page, it queries WordPress for draft content instead of published content.

The Implementation

Your preview API route:

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const secret = searchParams.get('secret');
  const id = searchParams.get('id');

  // Verify secret
  if (secret !== process.env.PREVIEW_SECRET) {
    return new Response('Invalid token', { status: 401 });
  }

  // Enable draft mode
  draftMode().enable();

  // Redirect to the post
  redirect(`/blog/${slug}`);
}

Then in your page component:

export default async function Post({ params }) {
  const { isEnabled } = draftMode();
  
  // Fetch draft if preview mode is enabled
  const post = await fetchPost(params.slug, {
    preview: isEnabled
  });
  
  return <PostTemplate post={post} />;
}

The WordPress Side

Our plugin adds a “Preview on Frontend” button to the WordPress editor that generates the preview URL automatically.

It also handles authentication – only logged-in WordPress users can generate preview links, keeping your drafts secure.

Exit Preview

We add a banner to preview pages:

{draftMode().isEnabled && (
  <div className="bg-yellow-100 p-4">
    <p>You are viewing a preview.</p>
    <a href="/api/exit-preview">Exit Preview</a>
  </div>
)}

The exit route simply clears the draft mode cookie.

Why This Matters

Without preview mode, editors have to publish content to see how it looks. This breaks their workflow and risks publishing unfinished work.

With FlatWP’s preview mode, editors can iterate on drafts, share preview links with teammates, and only publish when ready.

It’s a small feature that makes a huge difference in adoption.

Forms are everywhere – contact forms, newsletter signups, lead capture. Here’s how to handle them in a headless WordPress setup.

Approach 1: WordPress Forms (Recommended)

Use Contact Form 7 or WPForms in WordPress, submit from Next.js:

// Server action in Next.js
async function handleSubmit(formData: FormData) {
  const response = await fetch(
    'https://dev-cms.flatwp.com/wp-json/contact-form-7/v1/contact-forms/123/feedback',
    {
      method: 'POST',
      body: formData,
    }
  );
  
  return response.json();
}

Pros:

• Editors manage form fields in WordPress
• Email notifications handled by WordPress
• Submissions stored in WordPress database
• Works with existing WordPress plugins

Cons:

• Extra API call to WordPress
• WordPress becomes a dependency for forms

Approach 2: Next.js Server Actions

Handle forms entirely in Next.js with server actions:

// app/contact/actions.ts
'use server'

export async function submitContact(formData: FormData) {
  const data = {
    name: formData.get('name'),
    email: formData.get('email'),
    message: formData.get('message'),
  };
  
  // Send email via Resend, SendGrid, etc.
  await sendEmail(data);
  
  // Store in database if needed
  await db.contacts.create(data);
}

Pros:

• No WordPress dependency
• Full control over validation and processing
• Modern server actions pattern
• Can integrate with any email service

Cons:

• Editors can’t manage form fields
• Need separate storage for submissions
• More code to maintain

Approach 3: Third-Party Services

Use Formspree, Tally, or similar:

<form action="https://formspree.io/f/your-id" method="POST">
  <input name="email" type="email" />
  <button type="submit">Submit</button>
</form>

Pros:

• Zero backend code
• Spam protection included
• Email notifications handled
• Nice dashboard for submissions

Cons:

• Monthly cost ($0-$20)
• Less customization
• Another service to manage

FlatWP’s Approach

We include adapters for all three approaches. Our default recommendation:

• Use WordPress forms for marketing sites (editors need control)
• Use server actions for apps (more dynamic needs)
• Use third-party for MVPs (fastest to ship)

The beauty of headless is you’re not locked in. Start with one, switch to another as needs change.

Validation with Zod

Regardless of approach, validate with Zod:

const contactSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  message: z.string().min(10),
});

export async function submitContact(formData: FormData) {
  const data = contactSchema.parse({
    name: formData.get('name'),
    email: formData.get('email'),
    message: formData.get('message'),
  });
  
  // data is now typed and validated
}

Type-safe forms with runtime validation. Beautiful.