documenso-local-dev-loop
/documenso-local-dev-loop
Set up local development environment and testing workflow for Documenso. Use when configuring dev environment, setting up test workflows, or establishing rapid iteration patterns with Documenso. Trigger with phrases like "documenso local dev", "documenso development", "test documenso locally", "documenso dev environment".
- Author
- jeremylongshore ↗
- Repository
- tons-of-skills-marketplace ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 11
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Set up local development environment and testing workflow for Documenso. Use when configuring dev environment, setting up test workflows, or establishing rapid iteration patterns with Documenso. Trigger with phrases like "documenso local dev", "documenso development", "test documenso locally", "documenso dev environment".
Triggers from the description
Original author description
Set up local development environment and testing workflow for Documenso. Use when configuring dev environment, setting up test workflows, or establishing rapid iteration patterns with Documenso. Trigger with phrases like "documenso local dev", "documenso development", "test documenso locally", "documenso dev environment".
How it works
- Output
- Examples
- Overview
- Prerequisites
- Instructions
- Error Handling
- Resources
- Next Steps
SKILL.md preview
---
name: documenso-local-dev-loop
description: 'Set up local development environment and testing workflow for Documenso.
Use when configuring dev environment, setting up test workflows,
or establishing rapid iteration patterns with Documenso.
Trigger with phrases like "documenso local dev", "documenso development",
"test documenso locally", "documenso dev environment".
'
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(docker:*), Bash(node:*)
version: 1.14.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- documenso
- testing
- workflow
compatibility: Designed for Claude Code
---
# Documenso Local Dev Loop
## Output
- A small test-backed local change using synthetic documents/signers and a normal source-control rollback path.
- A redacted development verification receipt without document content, signing links, credentials, or signer PII.
## Examples
Use a development workspace with a synthetic template and signer, make one integration/config change, run its focused tests and a bounded lifecycle check, then inspect redacted status. Commit only reviewed changes; never use production documents, signing URLs, or credentials in local development.
## Overview
Configure a fast local development environment for Documenso integrations. Covers project structure, environment configs, self-hosted Documenso via Docker, test utilities, and cleanup scripts.
## Prerequisites
- Completed `documenso-install-auth` setup
- Node.js 18+ with TypeScript
- Docker (for self-hosted local Documenso)
## Instructions
### Step 1: Project Structure
```
my-signing-app/
├── src/
│ └── documenso/
│ ├── client.ts # Configured SDK client
│ ├── documents.ts # Document operations
│ ├── recipients.ts # Recipient management
│ └── webhooks.ts # Webhook handlers
├── scripts/
│ ├── verify-connection.ts # Quick health check
│ ├── create-test-doc.ts # Generate test documents
│ └── cleanup-test-docs.ts # Remove test data
├── tests/
│ └── integration/
│ ├── document.test.ts
│ └── template.test.ts
├── .env.development
├── .env.test
└── .env.production
```
### Step 2: Environment Configuration
**.env.development:**
```bash
DOCUMENSO_API_KEY=api_dev_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_dev_xxxxxxxxxxxx
LOG_LEVEL=debug
```
**.env.test:**
```bash
DOCUMENSO_API_KEY=api_test_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=https://stg-app.documenso.com/api/v2
DOCUMENSO_WEBHOOK_SECRET=whsec_test_xxxxxxxxxxxx
LOG_LEVEL=warn
```
### Step 3: Client Wrapper with Dev Helpers
```typescript
// src/documenso/client.ts
import { Documenso } from "@documenso/sdk-typescript";
let _client: Documenso | null = null;
export function getClient(): Documenso {
if (!_client) {
_client = new Documenso({
apiKey: process.env.DOCUMENSO_API_KEY!,
...(process.env.DOCUMENSO_BASE_URL && {
serverURL: process.env.DOCUMENSO_BASE_URL,
}),
});
}
return _client;
}
// Dev helper: list recent documents for debugging
export async function listRecentDocs(limit = 5) {
const client = getClient();
const { documents } = await client.documents.findV0({
page: 1,
perPage: limit,
orderByColumn: "createdAt",
orderByDirection: "desc",
});
return documents;
}
```
### Step 4: Self-Hosted Local Documenso (Docker)
```bash
# Pull the official Documenso Docker image
docker pull documenso/documenso:latest
# Create docker-compose.local.yml
```
```yaml
# docker-compose.local.yml
services:
documenso:
image: documenso/documenso:latest
ports:
- "3000:3000"
environment:
- NEXTAUTH_URL=http://localhost:3000
- NEXTAUTH_SECRET=local-dev-secret-change-me
- NEXT_PRIVATE_ENCRYPTION_KEY=local-encryption-key
- NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY=local-secondary-key
- NEXT_PUBLIC_WEBAPP_URL=http://localhost:3000
- NEXT_PRIVATE_DATABASE_URL=${DOCUMENSO_DATABASE_URL}
- NEXT_PRIVATE_DIRECT_DATABASE_URL=${DOCUMENSO_DIRECT_DATABASE_URL}
- NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
- NEXT_PRIVATE_SMTP_HOST=mailhog
- NEXT_PRIVATE_SMTP_PORT=1025
depends_on:
- db
- mailhog
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: documenso
POSTGRES_PASSWORD: password
POSTGRES_DB: documenso
volumes:
- pgdata:/var/lib/postgresql/data
mailhog:
image: mailhog/mailhog
ports:
- "8025:8025" # Web UI for email inspection
- "1025:1025"
volumes:
pgdata:
```
```bash
docker compose -f docker-compose.local.yml up -d
# Documenso at http://localhost:3000
# MailHog at http://localhost:8025 (view sent emails)
```
**.env.local (for self-hosted dev):**
```bash
DOCUMENSO_API_KEY=api_local_xxxxxxxxxxxx
DOCUMENSO_BASE_URL=http://localhost:3000/api/v2
```
### Step 5: Quick Verification Script
```typescript
// scripts/verify-connection.ts
import { getClient } from "../src/documenso/client";
async function verify() {
const client = getClient();
try {
const { documents } = await client.documents.findV0({ page: 1, perPage: 1 });
console.log("Connection OK");
console.log(`Documents accessible: ${documents.length >= 0 ? "yes" : "no"}`);
} catch (err: any) {
console.error(`Connection FAILED: ${err.message}`);
if (err.statusCode === 401) console.error("Check DOCUMENSO_API_KEY");
process.exit(1);
}
}
verify();
```
### Step 6: Test Cleanup Script
```typescript
// scripts/cleanup-test-docs.ts
import { getClient } from "../src/documenso/client";
async function cleanup() {
const client = getClient();
const { documents } = await client.documents.findV0({ page: 1, perPage: 100 });
const testDocs = documents.filter((d: any) =>
d.title.startsWith("[TEST]") || d.title.startsWith("Hello World")
);
for (const doc of testDocs) {
if (doc.status === "DRAFT") {
await client.documents.deleteV0(doc.id);
console.log(`Deleted: ${doc.title} (${doc.id})`);
} else {
console.log(`Skipped (${doc.status}): ${doc.title}`);
}
}
console.log(`Cleaned up ${testDocs.filter((d: any) => d.status === "DRAFT").length} test docs`);
}
cleanup();
```
### Step 7: Development Scripts (package.json)
```json
{
"scripts": {
"dev:verify": "tsx scripts/verify-connection.ts",
"dev:test-doc": "tsx scripts/create-test-doc.ts",
"dev:cleanup": "tsx scripts/cleanup-test-docs.ts",
"dev:local": "docker compose -f docker-compose.local.yml up -d",
"dev:local:stop": "docker compose -f docker-compose.local.yml down",
"test:integration": "vitest run tests/integration/"
}
}
```
## Error Handling
| Issue | Cause | Solution |
|-------|-------|----------|
| `ECONNREFUSED localhost:3000` | Docker not running | Run `docker compose up -d` |
| `401 on staging` | Wrong API key for env | Check `.env.development` key matches staging |
| Stale test data | Tests didn't clean up | Run `npm run dev:cleanup` |
| Rate limited in tests | Too many requests | Add `await delay(500)` between API calls |
| Emails not arriving | SMTP misconfigured | Check MailHog at `localhost:8025` |
## Resources
- [Documenso Self-Hosting](https://docs.documenso.com/developers/self-hosting/how-to)
- [Developer Quickstart](https://docs.documenso.com/docs/developers/local-development/quickstart)
- [Environment Variables Reference](https://docs.documenso.com/docs/self-hosting/configuration/environment)
- [MailHog](https://github.com/mailhog/MailHog)
## Next Steps
Apply patterns in `documenso-sdk-patterns` for production-ready code structure.
Files in this package (2)
- SKILL.md 8 KB
- references/implementation-guide.md 8 KB
Versions
The database has no other skills named documenso-local-dev-loop.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version ff3c1f76cf6a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100linear-local-dev-loop
Set up local Linear development environment and testing workflow. Use when configuring local development, testing integrations, or setting up a development workflow with Linear. Trigger with phrases like "linear local development", "linear dev setup", "test linear locally",… - 100documenso-install-auth
Install and configure Documenso SDK/API authentication. Use when setting up a new Documenso integration, configuring API keys, or initializing Documenso in your project. Trigger with phrases like "install documenso", "setup documenso", "documenso auth", "configure documenso API key". - 100documenso-sdk-patterns
Apply production-ready Documenso SDK patterns for TypeScript and Python. Use when implementing Documenso integrations, refactoring SDK usage, or establishing team coding standards for Documenso. Trigger with phrases like "documenso SDK patterns", "documenso best practices",… - 100deepgram-local-dev-loop
Configure Deepgram local development workflow with testing and iteration. Use when setting up development environment, configuring test fixtures, or establishing rapid iteration patterns for Deepgram integration. Trigger with phrases like "deepgram local dev", "deepgram… - 100documenso-webhooks
Receive and authenticate Documenso webhooks. Use when setting up a Documenso webhook endpoint, verifying the X-Documenso-Secret header, debugging 401s or an empty secret header, or handling document events like DOCUMENT_SIGNED and DOCUMENT_COMPLETED.