Installation

1. Prerequisites

Before installing the SDK, verify that your development environment meets the minimum runtime requirements. The Pdffillr SDK depends on features introduced in Node.js 20 LTS - most importantly, the native global fetch API - and will not function correctly on earlier Node.js releases.

node --version
# Expected: v20.0.0 or higher
# e.g. v20.11.0

npm --version
# Expected: 9.0.0 or higher
# e.g. 10.2.4

2. Install the Package

The Pdffillr SDK is published on the npm registry as @pdffillr/sdk. Install it with a single command. npm resolves the dependency, downloads the package, and installs it into node_modules exactly as any other registry package.

npm install @pdffillr/sdk

After installation completes, npm automatically adds the dependency entry to your package.json and generates a lock-file entry. Team members and CI pipelines running npm install on a fresh clone will install the exact same version, keeping your dependency pinned.

{
  "dependencies": {
    "@pdffillr/sdk": "^1.0.0"
  }
}

3. Set Up Your API Key

The SDK authenticates every request to the Pdffillr API using an API key. The recommended way to supply this key is through the PDFFILLR_API_KEY environment variable, which the SDK reads automatically at runtime. You configure this variable in a .env file that lives at the root of your project and is never committed to version control.

# .gitignore
.env
.env.local
.env.production
node_modules/

# .env
# Replace the placeholder value with your actual Pdffillr API key.
# Never commit this file to version control.
PDFFILLR_API_KEY=your_api_key_here

4. Load Environment Variables

Node.js does not automatically read .env files. You need a loader - the standard choice is dotenv - to parse the file and populate process.env before any module that reads those variables is imported. Installing and calling the loader at the very top of your application entry point is the recommended pattern.

npm install dotenv

// Entry point of your application - e.g. src/index.ts
// Import dotenv/config before any other module that reads process.env.
import 'dotenv/config';

import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});

// CommonJS entry point - e.g. src/index.js
require('dotenv').config();

const Pdffillr = require('@pdffillr/sdk');

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});

5. Verify the Install

Once the package is installed and your environment variable is configured, run two quick checks to confirm everything is in place before you write any application code. Catching a misconfiguration at this stage is far faster than debugging it mid-feature.

ls node_modules | grep pdffillr
# Expected output:
# @pdffillr

// smoke-test.ts  -  run with: npx ts-node smoke-test.ts
import 'dotenv/config';
import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});

// If this line executes without throwing, your install is working.
console.log('SDK client ready:', typeof client);

6. Module System Support

The Pdffillr SDK ships both an ESM build and a CommonJS build. npm automatically selects the correct build based on your project's module system. You do not need to configure anything - just import the package using the syntax that matches your codebase.

// TypeScript / modern ESM  (package.json "type": "module")
import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});

// CommonJS  (default Node.js module system)
const Pdffillr = require('@pdffillr/sdk');

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});