NamCaoDev
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:
npm install @namcaodev/postman-codegen
# or
yarn 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:
/**
* @namcaodev/postman-codegen configuration.
*
* @type {import("@namcaodev/postman-codegen").CodegenConfig}
*/
module.exports = {
generateType: 'seperate', // 'seperate' | 'combine',
generateMode: 'json_file', // 'fetch' | 'json_file'
postmanFetchConfigs: {
collectionId: '<YOUR_COLLECTION_ID>',
collectionAccessKey: '<YOUR_COLLECTION_ACCESS_KEY>'
}, // Config for fetch Postman document (Require when generate mode is fetch)
postmanJsonPath: "examples/postman-collection.json", // Postman Json Path (Require when generate mode is json_file)
generateOutputPath: "examples/generated", // Generated Folder path
propertyApiGetList: "items", // API response field containing list data
enableZodGeneration: true, // Enable zod schema generation
typeConfigs: {
allPropertiesOptional: true, // Mark all properties as optional
inferEnums: true, // inferEnums to string
inferDateTimes: true, // inferDateTimes to string
}, // Type configs for generate (Optional)
fetcher: "../../../helpers/fetcher", // Link to your custom fetcher
generateFileNames: {
requestType: "apiRequests.ts",
queryType: "apiQueries.ts",
responseType: "apiResponses.ts",
queryOptions: "query.ts",
mutationOptions: "mutation.ts",
}, // Customize generated file names (Optional)
};2. Run the command
After adding the configuration file, run the following command to generate the code:
npx postman-codegenThe 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
import React from "react";
import { useQuery } from "@tanstack/react-query";
import {
newmanGetRequestQueryOptions,
newmanGetRequestQueryKeys,
} from "./generated/newman-get-request/query";
const DemoCodegen = () => {
const query = useQuery({
...newmanGetRequestQueryOptions({
source: "test",
}),
});
const queryKeys = newmanGetRequestQueryKeys({ source: "test" });
console.log("Data response", query);
console.log("Query keys", queryKeys);
return <div>DemoCodegen</div>;
};
export default DemoCodegen;⚠️ Warning
With your custom fetcher you must follow the standard interface and function creation here:
export interface CustomFetchParams<TBody> {
url: string;
method: string;
options?: RequestInit;
body?: TBody;
}
export const customFetch = async <TResponseData = undefined, TBody = undefined>(
params: CustomFetchParams<TBody>
): Promise<TResponseData> => {
// You will handle your fetch here
};
export default customFetch; // You must be export default itYou 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', bothpostmanFetchConfigs.collectionIdandpostmanFetchConfigs.collectionAccessKeyare 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!
git clone https://github.com/NamCaoDev/postman-codegen.git
cd postman-codegen
npm install
npx 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! 🚀