klasik 1.0.17 → 1.0.19

package/README.md

@@ -95,6 +95,9 @@ Generate a TypeScript client from an OpenAPI spec (remote URL or local file).
 - `-u, --url <url>` - URL or file path to the OpenAPI spec (required)
   - Supports: `https://...`, `http://...`, `file://...`, `/absolute/path`, `./relative/path`
 - `-o, --output <dir>` - Output directory for generated client code (required)
+- `-m, --mode <mode>` - Generation mode: `full` (models + APIs + config) or `models-only` (default: `full`)
+  - `full`: Generates complete axios client with APIs, models, and configuration
+  - `models-only`: Generates only model classes with class-transformer decorators (no API client code)
 - `-H, --header <header...>` - Custom headers for HTTP requests (format: "Key: Value")
   - Can be used multiple times for multiple headers
   - Perfect for authorization: `--header "Authorization: Bearer token"`
@@ -417,6 +420,78 @@ await new K8sClientGenerator().generate({
 });
 ```
 
+## Best Practices for Existing Projects
+
+When integrating klasik into an existing TypeScript project, follow these best practices to avoid conflicts:
+
+### Generate into a Subdirectory
+
+```bash
+# Generate models into src/generated to avoid overwriting project files
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./src/generated \
+  --mode models-only \
+  --resolve-refs
+```
+
+### Clean Up Generated Config Files
+
+klasik generates `package.json` and `tsconfig.json` files. Remove them after generation:
+
+```json
+// package.json
+{
+  "scripts": {
+    "generate-client": "npx klasik generate --url $API_URL --output ./src/generated --mode models-only --resolve-refs && npm run cleanup-generated",
+    "cleanup-generated": "rm -f ./src/generated/package.json ./src/generated/tsconfig*.json ./src/generated/.openapi-generator*"
+  }
+}
+```
+
+### TypeScript Configuration for class-transformer
+
+Add these settings to your `tsconfig.json` for compatibility:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "skipLibCheck": true  // Skip type checking in node_modules (recommended for class-transformer)
+  }
+}
+```
+
+### Models-Only Mode
+
+Use `--mode models-only` when you:
+- Only need data models with class-transformer decorators
+- Want to use your own API client (axios, fetch, etc.)
+- Are integrating into an existing project with its own HTTP layer
+- Want to avoid package.json/tsconfig.json conflicts
+
+```bash
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./src/generated \
+  --mode models-only  # ✅ Generates only models, no API client
+```
+
+### Full Mode
+
+Use `--mode full` (default) when you:
+- Want a complete ready-to-use axios client
+- Are starting a new project from scratch
+- Want automatic response transformation with class-transformer
+
+```bash
+npx klasik generate \
+  --url https://api.example.com/openapi.yaml \
+  --output ./api-client \
+  --mode full  # Generates complete client with APIs
+```
+
 ## Advanced Configuration
 
 ### Custom Error Handling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klasik",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "description": "Download OpenAPI specs from remote URLs and generate TypeScript clients with class-transformer support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",