Installation

This guide covers everything you need to know about installing and configuring Mantlz in your application.

Prerequisites

Before installing Mantlz, ensure your environment meets these requirements:

Node.js: v18.0.0 or higher
Next.js: v15.0.0 or higher
React: v19.0.0 or higher
Package Manager: npm, yarn, or pnpm

While Mantlz is built for Next.js, the core functionality works with any React 19+ application. Next.js integration provides the best experience.

SDK Installation

Install the Package

Install the @mantlz/nextjs package using your preferred package manager:

npm install @mantlz/nextjs

The SDK automatically installs required dependencies:

Form handling: react-hook-form, @hookform/resolvers
Validation: zod
UI components: Radix UI primitives
Styling utilities: tailwind-merge, clsx, class-variance-authority
Toast notifications: sonner
Theme support: next-themes

Verify Installation

Check that the package is correctly installed:

npm list @mantlz/nextjs

You should see output similar to:

@mantlz/nextjs@0.6.1

Environment Setup

Create Environment Variables

Create a .env.local file in your project root:

.env.local

# Mantlz API Configuration
NEXT_PUBLIC_MANTLZ_API_KEY=mk_your_api_key_here

# Optional: Custom API URL (defaults to https://api.mantlz.app)
# NEXT_PUBLIC_MANTLZ_API_URL=https://api.mantlz.app

Never commit .env.local to version control! Add it to your .gitignore file:

.gitignore

.env.local
.env*.local

API Key Configuration

You have three options for providing your API key:

Environment Variable (Recommended)
Direct String
Runtime Configuration

Set the key in .env.local and reference it:

<MantlzProvider apiKey={process.env.NEXT_PUBLIC_MANTLZ_API_KEY}>
  {children}
</MantlzProvider>

Pass the key directly (not recommended for production):

<MantlzProvider apiKey="mk_your_api_key">
  {children}
</MantlzProvider>

Create a client instance with custom configuration:

import { createMantlzClient } from '@mantlz/nextjs';

const client = createMantlzClient('mk_your_api_key', {
  apiUrl: 'https://api.mantlz.app',
  notifications: true,
  cache: {
    enabled: true,
    ttl: 300000 // 5 minutes
  }
});

Provider Configuration

Basic Setup

Wrap your application with MantlzProvider in your root layout:

app/layout.tsx

import { MantlzProvider } from '@mantlz/nextjs';
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'My App',
  description: 'My awesome app with Mantlz forms',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <MantlzProvider apiKey={process.env.NEXT_PUBLIC_MANTLZ_API_KEY}>
          {children}
        </MantlzProvider>
      </body>
    </html>
  );
}

Advanced Configuration

Customize the client behavior with additional options:

app/layout.tsx

import { MantlzProvider } from '@mantlz/nextjs';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <MantlzProvider 
          apiKey={process.env.NEXT_PUBLIC_MANTLZ_API_KEY}
        >
          {children}
        </MantlzProvider>
      </body>
    </html>
  );
}

Custom Client Configuration

For advanced use cases, create a custom client instance:

lib/mantlz.ts

import { createMantlzClient } from '@mantlz/nextjs';

export const mantlzClient = createMantlzClient(
  process.env.NEXT_PUBLIC_MANTLZ_API_KEY!,
  {
    // Custom API URL (optional)
    apiUrl: 'https://api.mantlz.app',
    
    // Enable/disable toast notifications
    notifications: true,
    
    // Show API key error toasts
    showApiKeyErrorToasts: false,
    
    // Cache configuration
    cache: {
      enabled: true,
      ttl: 300000 // 5 minutes in milliseconds
    },
    
    // CORS configuration
    credentials: 'include',
    
    // Custom logger for debugging
    logger: (message, ...args) => {
      if (process.env.NODE_ENV === 'development') {
        console.log('[Mantlz]', message, ...args);
      }
    }
  }
);

TypeScript Configuration

Mantlz is built with TypeScript and provides full type safety out of the box.

Type Imports

Import types for enhanced development experience:

import type { 
  MantlzProps,
  FormSchema,
  FormField,
  FormType,
  Appearance,
  MantlzClient,
  FormSubmitResponse 
} from '@mantlz/nextjs';

Example: Typed Component

components/ContactForm.tsx

import { Mantlz } from '@mantlz/nextjs';
import type { MantlzProps } from '@mantlz/nextjs';

interface ContactFormProps {
  formId: string;
  theme?: MantlzProps['theme'];
}

export function ContactForm({ formId, theme = 'default' }: ContactFormProps) {
  return (
    <Mantlz
      formId={formId}
      theme={theme}
      redirectUrl="/thank-you"
    />
  );
}

Styling Setup

Tailwind CSS Integration

Mantlz uses Tailwind CSS for styling. If you’re using Tailwind, add Mantlz to your content paths:

tailwind.config.js

module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@mantlz/nextjs/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

CSS Variables

Mantlz uses Radix UI color tokens. These are automatically injected, but you can customize them:

app/globals.css

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --mantlz-primary: #3b82f6;
  --mantlz-background: #ffffff;
  --mantlz-border-radius: 8px;
}

.dark {
  --mantlz-primary: #60a5fa;
  --mantlz-background: #1a1a1a;
}

Validation Setup

Mantlz uses Zod for runtime validation. The SDK handles this automatically, but you can extend validation:

import { z } from 'zod';
import { useMantlz } from '@mantlz/nextjs';

const customSchema = z.object({
  email: z.string().email('Invalid email format'),
  phone: z.string().regex(/^\+?[1-9]\d{1,14}$/, 'Invalid phone number'),
  website: z.string().url('Must be a valid URL').optional(),
});

// Use with form submission
function MyForm() {
  const { client } = useMantlz();
  
  const handleSubmit = async (data: z.infer<typeof customSchema>) => {
    const validated = customSchema.parse(data);
    
    await client?.submitForm('contact', {
      formId: 'form_abc123',
      data: validated,
    });
  };
  
  return (
    // Your form JSX
  );
}

Self-Hosted Setup

If you’re self-hosting Mantlz, point the SDK to your instance:

import { createMantlzClient } from '@mantlz/nextjs';

const client = createMantlzClient(
  process.env.NEXT_PUBLIC_MANTLZ_API_KEY!,
  {
    apiUrl: 'https://your-domain.com',
    credentials: 'include',
  }
);

Environment Variables for Self-Hosted

.env.local

NEXT_PUBLIC_MANTLZ_API_KEY=mk_your_api_key
NEXT_PUBLIC_MANTLZ_API_URL=https://your-mantlz-instance.com

Verification

Test Your Installation

Create a simple test component to verify everything works:

app/test/page.tsx

import { Mantlz } from '@mantlz/nextjs';

export default function TestPage() {
  return (
    <div className="min-h-screen flex items-center justify-center p-4">
      <div className="max-w-md w-full">
        <h1 className="text-2xl font-bold mb-6">Mantlz Installation Test</h1>
        
        <Mantlz
          formId="your_test_form_id"
          theme="default"
        />
      </div>
    </div>
  );
}

Navigate to /test in your browser. If you see your form, installation was successful!

Check the Console

Open your browser’s developer console. You should see:

No error messages
Form schema loaded successfully
Mantlz styles injected

Common Issues

Module Not Found

Error: Cannot find module '@mantlz/nextjs' Solution:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Type Errors

Error: Property 'apiKey' does not exist on type... Solution: Ensure TypeScript can find the types:

tsconfig.json

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "types": ["@mantlz/nextjs"]
  }
}

API Key Not Working

Issue: Forms not loading or API errors Checklist:

Verify API key starts with mk_
Check key is active in dashboard
Restart dev server after adding .env.local
Ensure key is in NEXT_PUBLIC_ variable

Styles Not Loading

Issue: Forms appear unstyled Solution: The provider automatically injects styles. Ensure:

MantlzProvider wraps your app
You’re importing components correctly
Check for CSS conflicts

Next Steps

Quickstart Guide

Create your first form in 5 minutes

Form Types

Explore different form types

Customization

Apply themes and custom styling

API Reference

Explore the full API

Getting Started

Platform

SDK

Guides

Pricing & Plans

Prerequisites

SDK Installation

Install the Package

Verify Installation

Environment Setup

Create Environment Variables

API Key Configuration

Provider Configuration

Basic Setup

Advanced Configuration

Custom Client Configuration

TypeScript Configuration

Type Imports

Example: Typed Component

Styling Setup

Tailwind CSS Integration

CSS Variables

Validation Setup

Self-Hosted Setup

Environment Variables for Self-Hosted

Verification

Test Your Installation

Check the Console

Common Issues

Module Not Found

Type Errors

API Key Not Working

Styles Not Loading

Next Steps

Quickstart Guide

Form Types

Customization

API Reference

Additional Resources

Getting Started

Platform

SDK

Guides

Pricing & Plans

Documentation Index

​Prerequisites

​SDK Installation

​Install the Package

​Verify Installation

​Environment Setup

​Create Environment Variables

​API Key Configuration

​Provider Configuration

​Basic Setup

​Advanced Configuration

​Custom Client Configuration

​TypeScript Configuration

​Type Imports

​Example: Typed Component

​Styling Setup

​Tailwind CSS Integration

​CSS Variables

​Validation Setup

​Self-Hosted Setup

​Environment Variables for Self-Hosted

​Verification

​Test Your Installation

​Check the Console

​Common Issues

​Module Not Found

​Type Errors

​API Key Not Working

​Styles Not Loading

​Next Steps

Quickstart Guide

Form Types

Customization

API Reference

​Additional Resources

Prerequisites

SDK Installation

Install the Package

Verify Installation

Environment Setup

Create Environment Variables

API Key Configuration

Provider Configuration

Basic Setup

Advanced Configuration

Custom Client Configuration

TypeScript Configuration

Type Imports

Example: Typed Component

Styling Setup

Tailwind CSS Integration

CSS Variables

Validation Setup

Self-Hosted Setup

Environment Variables for Self-Hosted

Verification

Test Your Installation

Check the Console

Common Issues

Module Not Found

Type Errors

API Key Not Working

Styles Not Loading

Next Steps

Additional Resources