Postman Codegen

Postman Codegen is a tool that helps you automatically generate typescript files, tanstack queries easily from postman json

✨ Features

• 📌 Support full feature codegen typescript, tanstack query for people
• ⚡ Optimized performance and easy to use
• 🔧 Easily integrates with TypeScript projects

📦 Installation

Install via npm or yarn:

1npm install @namcaodev/postman-codegen
2# or
3yarn add @namcaodev/postman-codegen

🚀 Usage

1. Create codegen.config.cjs

To configure the library, create a codegen.config.cjs file in your root project with the following examples options:

1/**
2 * @namcaodev/postman-codegen configuration.
3 *
4 * @type {import("@namcaodev/postman-codegen").CodegenConfig}
5 */
6
7module.exports = {
8  generateType: 'seperate', // 'seperate' | 'combine',
9  generateMode: 'json_file', // 'fetch' | 'json_file'
10  postmanFetchConfigs: {
11    collectionId: '<YOUR_COLLECTION_ID>',
12    collectionAccessKey: '<YOUR_COLLECTION_ACCESS_KEY>'
13  }, // Config for fetch Postman document (Require when generate mode is fetch)
14  postmanJsonPath: "examples/postman-collection.json", // Postman Json Path (Require when generate mode is json_file)
15  generateOutputPath: "examples/generated", // Generated Folder path
16  propertyApiGetList: "items", // API response field containing list data
17  enableZodGeneration: true, // Enable zod schema generation
18  typeConfigs: {
19    allPropertiesOptional: true, // Mark all properties as optional
20    inferEnums: true, // inferEnums to string
21    inferDateTimes: true, // inferDateTimes to string
22  }, // Type configs for generate (Optional)
23  fetcher: "../../../helpers/fetcher", // Link to your custom fetcher
24  generateFileNames: {
25    requestType: "apiRequests.ts",
26    queryType: "apiQueries.ts",
27    responseType: "apiResponses.ts",
28    queryOptions: "query.ts",
29    mutationOptions: "mutation.ts",
30  }, // Customize generated file names (Optional)
31};

2. Run the command

After adding the configuration file, run the following command to generate the code:

1npx postman-codegen

The generated files will be saved in the folder specified in generateOutputPath (e.g., generated).

3. Usage in React Component

Next, easy usage in your React Component with full type safe power demo.tsx

1import React from "react";
2import { useQuery } from "@tanstack/react-query";
3import {
4  newmanGetRequestQueryOptions,
5  newmanGetRequestQueryKeys,
6} from "./generated/newman-get-request/query";
7
8const DemoCodegen = () => {
9  const query = useQuery({
10    ...newmanGetRequestQueryOptions({
11      source: "test",
12    }),
13  });
14  const queryKeys = newmanGetRequestQueryKeys({ source: "test" });
15  console.log("Data response", query);
16  console.log("Query keys", queryKeys);
17  return <div>DemoCodegen</div>;
18};
19
20export default DemoCodegen;

⚠️ Warning

With your custom fetcher you must follow the standard interface and function creation here:

1export interface CustomFetchParams<TBody> {
2  url: string;
3  method: string;
4  options?: RequestInit;
5  body?: TBody;
6}
7
8export const customFetch = async <TResponseData = undefined, TBody = undefined>(
9  params: CustomFetchParams<TBody>
10): Promise<TResponseData> => {
11  // You will handle your fetch here
12};
13
14export default customFetch; // You must be export default it

You can see an example in the source code here: fetcher.ts and how it is handled here: queryWithParams.hbs.

🔧 Configuration Options

Option	Type	Required	Description
generateType	'seperate' | 'combine'	❌ No (Default: seperate)	'separate': Generates separate folders/files for each API path. 'combine': Merges all types and queries into a single file.
generateMode	'fetch' | 'json_file'	✅ Yes	Determines how data is retrieved from Postman. 'fetch' fetches the collection via API, while 'json_file' uses an exported JSON file.
postmanFetchConfigs.collectionId	string	🔹 If generateMode = 'fetch'	The Postman Collection ID to fetch.
postmanFetchConfigs.collectionAccessKey	string	🔹 If generateMode = 'fetch'	The API Key required to access the collection from Postman API.
postmanJsonPath	string	🔹 If generateMode = 'json_file'	Path to the exported Postman JSON file.
generateOutputPath	string	✅ Yes	Directory where the generated files will be stored.
propertyApiGetList	string	✅ Yes	The key containing the list of data in the API response.
enableZodGeneration	boolean	❌ No (Default: false)	If true, automatically generates Zod schemas.
typeConfigs.allPropertiesOptional	boolean	❌ No (Default: false)	If true, all properties will be optional.
typeConfigs.inferEnums	boolean	❌ No (Default: false)	If true, automatically infers enums from API responses.
typeConfigs.inferDateTimes	boolean	❌ No (Default: false)	If true, automatically detects datetime fields in responses.
fetcher	string	✅ Yes	Path to a custom fetcher function.
generateFileNames.requestType	string	❌ No (Default: apiRequests.ts)	Filename for API request definitions.
generateFileNames.queryType	string	❌ No (Default: apiQueries.ts)	Filename for API queries.
generateFileNames.responseType	string	❌ No (Default: apiResponses.ts)	Filename for API response types.
generateFileNames.queryOptions	string	❌ No (Default: query.ts)	Filename for query options.
generateFileNames.mutationOptions	string	❌ No (Default: mutation.ts)	Filename for mutation options.

📌 Notes:

• If generateMode = 'fetch', both postmanFetchConfigs.collectionId and postmanFetchConfigs.collectionAccessKey are required.

• If generateMode = 'json_file', postmanJsonPath is required.

• ⚡ Using generateMode = 'fetch' allows you to sync updates from your backend in Postman documents instantly.

🛠 Contributing

If you want to contribute, please fork the repository and submit a pull request!

1git clone https://github.com/NamCaoDev/postman-codegen.git
2cd postman-codegen
3npm install
4npx postman-codegen

📜 License

Distributed under the MIT License. See the LICENSE file for more details.

🌍 Contact

• 📧 Email: namcaodev@gmail.com
• 🐦 Twitter: @namcaodev

Thank you for using Postman Codegen Library! 🚀