# Userscript Quickstart

This quickstart guides you through creating, validating, and deploying your first userscript based on a cookbook example.

## Before you begin

- Install MOLT Replicator v1.3.0 or later for full compatibility with the userscript API.
- Install a TypeScript-compatible IDE (for example, VS Code).

## Step 1: Set up your environment

Create a new TypeScript file for your userscript in your IDE (for example, `userscript.ts`).

For IDE autocomplete and type-checking support, optionally add the Replicator TypeScript definitions. For details, refer to Access this API.

## Step 2: Write a userscript

Use the userscript cookbook as a starting point. The cookbook provides ready-to-use examples that you can copy and adapt.

Copy and adapt a cookbook example that matches your use case. For example, adapt the template to filter a single table to exclude the `audit_logs` table from the `public` schema during replication:

    import * as api from "replicator@v2";

    const TARGET_SCHEMA_NAME = "defaultdb.public";
    const TABLE_TO_SKIP = "audit_logs";

    api.configureTargetSchema(SCHEMA_NAME, {
      onRowUpsert: (row, meta) => {
        if (meta.table === TABLE_TO_SKIP) {
          return null; // Skip this table
        }
        return row;
      },
      onRowDelete: (row, meta) => {
        if (meta.table === TABLE_TO_SKIP) {
          return null;
        }
        return row;
      }
    });

For details on the userscript API and handler functions, refer to the Userscript API.

Tip:

When writing userscripts, follow the best practices.

## Step 3: Use with Replicator

Include the `--userscript` flag to have MOLT Replicator apply the userscript. For example, to apply your userscript during PostgreSQL replication:

    replicator pglogical \
    --sourceConn $SOURCE \
    --targetConn $TARGET \
    --targetSchema defaultdb.public \
    --slotName molt_slot \
    --publicationName molt_fetch \
    --stagingSchema defaultdb._replicator \
    --stagingCreateSchema \
    --userscript userscript.ts

## See also

- Userscript Overview
- Userscript API
- Userscript Cookbook
- MOLT Replicator