insomnia-collection-generator

name	insomnia-collection-generator
description	Generates Insomnia collection export files from Express, Next.js, Fastify, or other API routes. Creates organized workspaces with request groups, environments, and authentication. Use when users request "generate insomnia collection", "export to insomnia", "create insomnia workspace", or "insomnia import".

Insomnia Collection Generator

Generate importable Insomnia workspaces from your API codebase automatically.

Core Workflow

1. Scan routes: Find all API route definitions
2. Extract metadata: Methods, paths, params, bodies
3. Create workspace: Organize into request groups
4. Configure environments: Base URLs, auth tokens
5. Add authentication: Bearer, Basic, API Key
6. Export collection: Insomnia v4 JSON format

Insomnia Export v4 Schema

{
  "_type": "export",
  "__export_format": 4,
  "__export_date": "2024-01-15T10:30:00.000Z",
  "__export_source": "insomnia.desktop.app:v2023.5.8",
  "resources": []
}

Resource Types

interface InsomniaWorkspace {
  _id: string;
  _type: "workspace";
  name: string;
  description: string;
  scope: "collection" | "design";
}

interface InsomniaRequestGroup {
  _id: string;
  _type: "request_group";
  name: string;
  parentId: string;
  description?: string;
}

interface InsomniaRequest {
  _id: string;
  _type: "request";
  name: string;
  parentId: string;
  method: string;
  url: string;
  body: InsomniaBody;
  headers: InsomniaHeader[];
  parameters: InsomniaParameter[];
  authentication: InsomniaAuth;
}

interface InsomniaEnvironment {
  _id: string;
  _type: "environment";
  name: ;
  : ;
  : <, >;
}

Collection Generator

// scripts/generate-insomnia.ts
import { v4 as uuidv4 } from "uuid";

interface RouteInfo {
  method: string;
  path: string;
  name: string;
  body?: object;
  params?: { name: string; type: "path" | "query" }[];
}

interface InsomniaExport {
  _type: "export";
  __export_format: 4;
  __export_date: string;
  __export_source: string;
  resources: InsomniaResource[];
}

type InsomniaResource =
  | InsomniaWorkspace
  | InsomniaRequestGroup
  | InsomniaRequest
  | InsomniaEnvironment;

function generateInsomniaCollection(
  routes: RouteInfo[],
  options: {
    name: string;
    baseUrl: string;
    description?: string;
  }
): InsomniaExport {
  const workspaceId = `wrk_${uuidv4().replace(/-/g, )}`;
   baseEnvId = ;
   devEnvId = ;

   : [] = [];

  
  resources.({
    : workspaceId,
    : ,
    : options.,
    : options. || ,
    : ,
  });

  
  resources.({
    : baseEnvId,
    : ,
    : ,
    : workspaceId,
    : {},
  });

  
  resources.({
    : devEnvId,
    : ,
    : ,
    : baseEnvId,
    : {
      : options.,
      : ,
    },
  });

  
   groupedRoutes = (routes);

   ( [resource, resourceRoutes]  .(groupedRoutes)) {
    
     groupId = ;

    resources.({
      : groupId,
      : ,
      : (resource),
      : workspaceId,
      : ,
    });

    
     ( route  resourceRoutes) {
      resources.((route, groupId));
    }
  }

   {
    : ,
    : ,
    :  ().(),
    : ,
    resources,
  };
}

 ():  {
   requestId = ;

  
   url = route..(, );

   :  = {
    : requestId,
    : ,
    : route.,
    parentId,
    : route.,
    : ,
    : {
      : ,
      : route. ? .(route., , ) : ,
    },
    : [
      {
        : ,
        : ,
      },
    ],
    : route.
      ?.( p. === )
      .( ({
        : p.,
        : ,
        : ,
      })) || [],
    : {
      : ,
      : ,
      : ,
    },
  };

   request;
}

 (): <, []> {
   : <, []> = {};

   ( route  routes) {
     parts = route..().();
     resource = parts[] || ;

     (!groups[resource]) {
      groups[resource] = [];
    }
    groups[resource].(route);
  }

   groups;
}

 ():  {
   str.().() + str.();
}

Complete Export Example

{
  "_type": "export",
  "__export_format": 4,
  "__export_date": "2024-01-15T10:30:00.000Z",
  "__export_source": "api-generator:v1.0.0",
  "resources": [
    {
      "_id": "wrk_abc123",
      "_type": "workspace",
      "name": "My API",
      "description": "Auto-generated API collection",
      "scope": "collection"
    },
    {
      "_id": "env_base123",
      "_type": "environment",
      "name": "Base Environment",
      "parentId": 
       
    
    
       
       
       
       
       
         
         
      
    
    
       
       
       
       
       
         
         
      
    
    
       
       
       
       
    
    
       
       
       
       
       
       
       
       
             
      
       
               
               
      
       
         
         
      
    
    
       
       
       
       
       
       
       
       
       
    
    
       
       
       
       
       
       
       
         
         
      
       
             
      
       
         
         
      
    
  

Authentication Types

// Bearer Token
{
  "type": "bearer",
  "token": "{{ _.auth_token }}",
  "prefix": "Bearer"
}

// Basic Auth
{
  "type": "basic",
  "username": "{{ _.username }}",
  "password": "{{ _.password }}"
}

// API Key
{
  "type": "apikey",
  "key": "X-API-Key",
  "value": "{{ _.api_key }}",
  "addTo": "header"
}

// OAuth 2.0
{
  "type": "oauth2",
  "grantType": "authorization_code",
  "authorizationUrl": "https://auth.example.com/authorize",
  "accessTokenUrl": "https://auth.example.com/token",
  "clientId": "{{ _.client_id }}",
  "clientSecret": "{{ _.client_secret }}",
  "scope": "read write"
}

Request Body Types

// JSON Body
{
  "mimeType": "application/json",
  "text": "{\"name\": \"value\"}"
}

// Form URL Encoded
{
  "mimeType": "application/x-www-form-urlencoded",
  "params": [
    { "name": "field1", "value": "value1" },
    { "name": "field2", "value": "value2" }
  ]
}

// Multipart Form (file upload)
{
  "mimeType": "multipart/form-data",
  "params": [
    { "name": "file", "type": "file", "fileName": "" },
    { "name": "description", "value": "File description" }
  ]
}

// GraphQL
{
  "mimeType": "application/graphql",
  "text": "query { users { id name } }"
}

CLI Script

#!/usr/bin/env node
// scripts/insomnia-gen.ts
import * as fs from "fs";
import { program } from "commander";

program
  .name("insomnia-gen")
  .description("Generate Insomnia collection from API routes")
  .option("-f, --framework <type>", "Framework type", "express")
  .option("-s, --source <path>", "Source directory", "./src")
  .option("-o, --output <path>", "Output file", "./insomnia-collection.json")
  .option("-n, --name <name>", "Workspace name", "API Collection")
  .option("-b, --base-url <url>", "Base URL", "http://localhost:3000/api")
  .parse();

const options = program.opts();

async function main() {
  const routes = await scanRoutes(options.framework, options.source);

  const collection = generateInsomniaCollection(routes, {
    name: options.name,
    : options.,
  });

  fs.(options., .(collection, , ));
  .();
}

();

Environment Templates

{
  "_id": "env_development",
  "_type": "environment",
  "name": "Development",
  "data": {
    "base_url": "http://localhost:3000/api",
    "auth_token": "",
    "user_id": "1"
  }
}

{
  "_id": "env_staging",
  "_type": "environment",
  "name": "Staging",
  "data": {
    "base_url": "https://staging-api.example.com",
    "auth_token": "",
    "user_id": "test-user-123"
  }
}

{
  "_id": "env_production",
  "_type": "environment",
  "name": "Production",
  "data": {
    "base_url": "https://api.example.com",
    "auth_token": "",
    "user_id": ""
  }
}

Best Practices

1. Use environments: Store base URLs and tokens as variables
2. Organize folders: Group requests by resource/feature
3. Template syntax: Use {{ _.variable }} for dynamic values
4. Authentication: Configure at workspace level when possible
5. Add descriptions: Document each request's purpose
6. Include examples: Pre-fill request bodies with realistic data
7. Version control: Commit export JSON to repository
8. Multiple envs: Create dev, staging, production environments

Output Checklist

• All routes scanned from codebase
• Workspace created with proper scope
• Request groups organized by resource
• Requests include proper methods and URLs
• Path parameters converted to {{ _.param }} syntax
• Request bodies included for POST/PUT/PATCH
• Headers configured (Content-Type, etc.)
• Environments created (dev, staging, prod)
• Authentication configured
• Export validates in Insomnia