External LibrariesGetting Started

Getting Started

Create and deploy your first external library in under 10 minutes.

Prerequisites

  • Node.js 18+
  • npm or pnpm
  • A ReAPI account with a project

Step 1: Clone the Template

git clone https://github.com/ReAPI-com/external-lib-template my-test-lib
cd my-test-lib
npm install

Step 2: Explore the Structure

my-test-lib/
├── src/
│   ├── assertions/       # Custom assertion functions
│   │   └── index.ts
│   ├── generators/       # Value generator functions
│   │   └── index.ts
│   ├── hooks/            # API hooks (before/after)
│   │   └── index.ts
│   ├── test-cases/       # External test cases
│   │   └── index.ts
│   ├── utils/            # Shared utilities
│   │   └── index.ts
│   └── index.ts          # Main export file
├── dist/                 # Build output
├── package.json
├── tsconfig.json
└── rollup.config.js      # Builds UMD bundle

Step 3: Write a Simple Assertion

Edit src/assertions/index.ts:

import type { AssertionFunction } from "../types";
 
export const isPositiveNumber: AssertionFunction = {
  id: "is-positive-number",
  name: "Is Positive Number",
  description: "Checks if a value is a positive number",
  enabled: true,
  deprecated: false,
  tested: true,
  function: async (value: unknown) => {
    const passed = typeof value === "number" && value > 0;
 
    $addAssertionResult({
      passed,
      message: passed
        ? `${value} is a positive number`
        : `Expected positive number, got ${value}`,
      operator: "isPositiveNumber",
      leftValue: value,
      rightValue: "> 0",
    });
  },
};
 
// Export all assertions
export const $$AssertionFunctions = [isPositiveNumber];

Step 4: Build the Library

npm run build

This creates:

  • dist/build.umd.js - The library bundle
  • dist/build.d.ts - TypeScript declarations

Step 5: Deploy to ReAPI

Use the ReAPI CLI to build and sync your library directly to the platform. This is faster and more secure than publishing to npm.

# Install CLI if you haven't already
npm install -g @reapi/cli
 
# Login to your account
reapi login
 
# Sync to your project
# Replace <project-id> with your actual project ID (found in Project Settings)
reapi lib sync --project <project-id>

The CLI will:

  1. Build your library automatically
  2. Upload the bundle to ReAPI’s secure CDN
  3. Register/Update the library in your project

Step 6: Verify in ReAPI

  1. Go to Project Settings → External Libraries
  2. You should see “My Test Library” listed and enabled
  3. The status should be “Synced” with the latest version

Alternative: Deploy via npm (Legacy)

If you prefer using npm:

  1. Run npm publish --access public
  2. Go to ReAPI Project Settings → External Libraries
  3. Manually add the unpkg.com URL (e.g., https://unpkg.com/my-lib/dist/build.umd.js)

Step 7: Use in Tests

Your isPositiveNumber assertion is now available:

  • In Assert Node → Select “Is Positive Number” from operators
  • In Script Node → Call MyTestLib.isPositiveNumber(value)

Quick Reference

CommandPurpose
npm run buildBuild the library
npm run testRun unit tests
npm run lintCheck code quality
reapi lib syncDeploy to ReAPI (Recommended)
npm publishDeploy to npm (Legacy)

Next Steps

How It WorksComponent Basics