Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 3 additions & 73 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,13 +128,13 @@ export default defineNuxtConfig({
modules: ['nuxt-apex'],
apex: {
sourcePath: 'api', // API source folder
outputPath: 'composables/.nuxt-apex', // Output for composables
cacheFolder: 'node_modules/.cache/nuxt-apex', // Output for cache
outputPath: '.nuxt/nuxt-apex/files', // Output for composables
cacheFolder: '.nuxt/nuxt-apex/cache', // Output for cache
composablePrefix: 'useTFetch', // Composable prefix
namingFunction: undefined, // Custom naming function
listenFileDependenciesChanges: true, // Watch for file changes
serverEventHandlerName: 'defineApexHandler', // Server event handler name
tsConfigFilePath: undefined, // Path to tsconfig.json
tsConfigFilePath: 'simple', // Path to tsconfig.json or 'simple' that create a simple one config especially for nuxt-apex module
ignore: ['api/internal/**'], // Patterns to ignore
concurrency: 50, // Concurrency limit
tsMorphOptions: { /* ... */ }, // ts-morph options
Expand Down Expand Up @@ -216,73 +216,3 @@ const { data, pending, error, execute } = useTFetchPostsGetById(
}
)
```

## Notes on Output

⚠️ **Important**: Composables must be generated inside the `composables/` directory (not `.nuxt` or `node_modules`) to work properly with Nuxt's auto-import system.

**Why this matters:**

Nuxt has special behavior for the `composables/` folder:
- Only files in `composables/` (or subfolders) are automatically registered as true composables
- Files outside this folder are treated as regular utilities and lose Nuxt context
- This means they can't access SSR context, plugins, or other Nuxt runtime features

**What happens if you put them elsewhere:**

```ts
// ❌ If composables are in .nuxt/ or node_modules/
const data = useTFetchPostsGetById({ id: 42 })
// Error: "useFetch can only be used within a Nuxt app setup function"
```

**The fix is simple** - just ensure your `outputPath` points to somewhere inside `composables/`:

```ts
// nuxt.config.ts ✅
apex: {
outputPath: 'composables/.nuxt-apex', // Inside composables/ - works perfectly
// outputPath: '.nuxt/apex', // ❌ Outside composables/ - breaks
}
```

**Default behavior:** nuxt-apex automatically uses `composables/.nuxt-apex` as the output path, so this works out of the box. Only change it if you need a custom structure.

### Cache Location Strategy

nuxt-apex uses caching to speed up composable generation. You have two options:

**Option 1: Default (node_modules cache)**
```ts
apex: {
cacheFolder: 'node_modules/.cache/nuxt-apex' // Default
}
```
**Pros:**
- ✅ Keeps your project clean - cache files don't clutter your source code
- ✅ Gitignored by default - no accidental commits of cache files
- ✅ Standard location that tools expect

**Cons:**
- ❌ Cache is lost when `node_modules` is deleted or with `git pull` conflicts
- ❌ Slower regeneration after fresh installs

**Option 2: Local cache (synced with git)**
```ts
apex: {
cacheFolder: 'composables/.nuxt-apex/'
}
```
**Pros:**
- ✅ Cache survives `node_modules` deletion
- ✅ Faster setup for new team members (cache comes with git clone)
- ✅ More predictable builds across environments

**Cons:**
- ❌ Cache files are committed to your repository
- ❌ Larger git repository size
- ❌ Potential merge conflicts in cache files

**Recommendation:** Use the default unless you have a large API and slow generation times, or your team frequently deletes `node_modules`.

**Default behavior:** nuxt-apex automatically uses `composables/.nuxt-apex` as the output path, so this works out of the box. Only change it if you need a custom structure.
47 changes: 24 additions & 23 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -73,37 +73,38 @@
"cy:open": "cypress open"
},
"dependencies": {
"@nuxt/kit": "3.17.7",
"chalk": "^5.4.1",
"@nuxt/kit": "4.2.1",
"chalk": "^5.6.2",
"node-persist": "^4.0.4",
"p-limit": "^6.2.0",
"tinyglobby": "^0.2.14",
"ts-morph": "^26.0.0",
"p-limit": "^7.2.0",
"tinyglobby": "^0.2.15",
"ts-morph": "^27.0.2",
"xxhash-wasm": "^1.1.0",
"zod": "^4.0.5"
"zod": "^4.1.13"
},
"devDependencies": {
"@commitlint/cli": "^19.8.1",
"@commitlint/config-conventional": "^19.8.1",
"@nuxt/devtools": "^2.6.2",
"@nuxt/module-builder": "^1.0.1",
"@nuxt/schema": "3.17.7",
"@nuxt/test-utils": "^3.19.2",
"@commitlint/cli": "^20.2.0",
"@commitlint/config-conventional": "^20.2.0",
"@nuxt/devtools": "^3.1.1",
"@nuxt/module-builder": "^1.0.2",
"@nuxt/schema": "4.2.1",
"@nuxt/test-utils": "^3.21.0",
"@semantic-release/commit-analyzer": "^13.0.1",
"@semantic-release/github": "^11.0.3",
"@semantic-release/npm": "^12.0.2",
"@semantic-release/release-notes-generator": "^14.0.3",
"@semantic-release/github": "^12.0.2",
"@semantic-release/npm": "^13.1.2",
"@semantic-release/release-notes-generator": "^14.1.0",
"@types/node": "latest",
"@types/node-persist": "^3.1.8",
"conventional-changelog-conventionalcommits": "^9.1.0",
"cypress": "^14.5.2",
"cypress": "^15.7.1",
"cypress-wait-until": "^3.0.2",
"memfs": "^4.17.2",
"nuxt": "3.17.7",
"semantic-release": "^24.2.7",
"typescript": "~5.8.3",
"vitest": "^3.2.4",
"vue-tsc": "^3.0.3"
"defu": "^6.1.4",
"memfs": "^4.51.1",
"nuxt": "4.2.1",
"semantic-release": "^25.0.2",
"typescript": "~5.9.3",
"vitest": "^4.0.15",
"vue-tsc": "^3.1.5"
},
"packageManager": "pnpm@10.13.1"
"packageManager": "pnpm@10.24.0"
}

This file was deleted.

This file was deleted.

This file was deleted.

17 changes: 0 additions & 17 deletions playground/composables/.nuxt-apex/composables/useTFetchGetByPid.ts

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

Loading