Skip to main content

Installation

Install the Easy Node.js SDK in your server-side project.

Package Installation​

npm install @easylabs/node
# or
yarn add @easylabs/node
# or
pnpm add @easylabs/node

Requirements​

  • Node.js: 20.0 or higher
  • TypeScript: 5.0+ (recommended but optional)

Getting Your API Key​

  1. Sign up at itseasy.co
  2. Navigate to your dashboard
  3. Generate a secret API key for server-side use
Security Warning

Your secret API key provides full access to your Easy account. Treat it like a password:

  • ✅ Store in environment variables
  • ✅ Never commit to version control
  • ✅ Never expose in client-side code
  • ✅ Rotate regularly
  • ✅ Use different keys for development and production

Environment Setup​

Node.js / Express​

Create a .env file in your project root:

EASY_API_KEY=your_secret_key_here
NODE_ENV=development

Install and configure dotenv:

npm install dotenv

Load environment variables:

import dotenv from "dotenv";
dotenv.config();

import { createClient } from "@easylabs/node";

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY,
  __dev: process.env.NODE_ENV === "development",
});

Next.js​

Create a .env.local file:

EASY_API_KEY=your_secret_key_here

Use in API routes:

// app/api/checkout/route.ts (App Router)
import { createClient } from "@easylabs/node";

export async function POST(request: Request) {
  const easy = await createClient({
    apiKey: process.env.EASY_API_KEY!,
  });

  // Your logic here
}
// pages/api/checkout.ts (Pages Router)
import { createClient } from "@easylabs/node";
import type { NextApiRequest, NextApiResponse } from "next";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const easy = await createClient({
    apiKey: process.env.EASY_API_KEY!,
  });

  // Your logic here
}

AWS Lambda​

import { createClient } from "@easylabs/node";

export const handler = async (event: any) => {
  const easy = await createClient({
    apiKey: process.env.EASY_API_KEY!,
  });

  // Your logic here
};

Vercel Serverless​

Add environment variable in Vercel dashboard, then use:

import { createClient } from "@easylabs/node";

export default async function handler(req, res) {
  const easy = await createClient({
    apiKey: process.env.EASY_API_KEY,
  });

  // Your logic here
}

TypeScript Configuration​

If using TypeScript, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Verification​

Verify the installation:

import { createClient } from "@easylabs/node";

const easy = await createClient({
  apiKey: process.env.EASY_API_KEY!,
});

// Test the connection
const customers = await easy.getCustomers({ limit: 1 });
console.log("Connected successfully!", customers);

Security Best Practices​

Use a Secrets Manager (Production)​

For production environments, consider using a secrets manager:

AWS Secrets Manager​

import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from "@aws-sdk/client-secrets-manager";

async function getApiKey() {
  const client = new SecretsManagerClient({ region: "us-east-1" });
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: "easy-api-key" }),
  );
  return JSON.parse(response.SecretString!).apiKey;
}

const apiKey = await getApiKey();
const easy = await createClient({ apiKey });

Google Secret Manager​

import { SecretManagerServiceClient } from "@google-cloud/secret-manager";

async function getApiKey() {
  const client = new SecretManagerServiceClient();
  const [version] = await client.accessSecretVersion({
    name: "projects/PROJECT_ID/secrets/easy-api-key/versions/latest",
  });
  return version.payload!.data!.toString();
}

const apiKey = await getApiKey();
const easy = await createClient({ apiKey });

Separate Development and Production Keys​

const easy = await createClient({
  apiKey:
    process.env.NODE_ENV === "production"
      ? process.env.EASY_API_KEY_PROD
      : process.env.EASY_API_KEY_DEV,
  __dev: process.env.NODE_ENV !== "production",
});

Next Steps​