### crawlFrameworkPkgs(options)

Source: https://context7.com/bluwy/vitefu/llms.txt

Crawls the dependency graph to determine Vite's optimizeDeps and ssr configurations for framework packages. It respects existing user configurations and provides deterministic output.

```APIDOC
## crawlFrameworkPkgs(options)

### Description
Crawls the dependency graph starting from the project root and returns `optimizeDeps.include/exclude` and `ssr.noExternal/external` arrays that tell Vite how to handle every framework-aware package. Framework packages are excluded from optimization and marked `ssr.noExternal`; their CJS transitive deps are deep-included; non-root CJS deps are SSR-externalized in dev mode. Respects an existing `viteUserConfig` so that explicit user overrides are never clobbered. Results are sorted for deterministic output.

### Parameters
#### Path Parameters
- **options** (object) - Required - Configuration options for crawling framework packages.
  - **root** (string) - Required - Absolute path to the project root (where package.json lives).
  - **isBuild** (boolean) - Required - `true` during `vite build`, `false` during `vite dev`.
  - **workspaceRoot** (string) - Optional - Enables crawling devDependencies of private workspace packages.
  - **viteUserConfig** (object) - Optional - The user's Vite config, to preserve existing settings.
  - **isFrameworkPkgByName** (function) - Optional - Callback to identify framework packages by name.
  - **isFrameworkPkgByJson** (function) - Optional - Callback to identify framework packages by inspecting package.json.
  - **isSemiFrameworkPkgByName** (function) - Optional - Callback to identify semi-framework packages by name.
  - **isSemiFrameworkPkgByJson** (function) - Optional - Callback to identify semi-framework packages by inspecting package.json.

### Returns
- **object** - An object containing Vite configuration sections.
  - **optimizeDeps** (object)
    - **include** (array) - Dependencies to include in optimization.
    - **exclude** (array) - Dependencies to exclude from optimization.
  - **ssr** (object)
    - **noExternal** (array) - Dependencies not to externalize during SSR.
    - **external** (array) - Dependencies to externalize during SSR.

### Request Example
```ts
import { crawlFrameworkPkgs, searchForWorkspaceRoot } from 'vitefu'

const result = await crawlFrameworkPkgs({
  root: process.cwd(),
  isBuild: false,
  workspaceRoot: searchForWorkspaceRoot(process.cwd()),
  viteUserConfig: userConfig,
  isFrameworkPkgByName(pkgName) {
    if (pkgName === 'my-framework') return true
    if (pkgName.startsWith('@my-framework/')) return true
    return undefined
  },
  isFrameworkPkgByJson(pkgJson) {
    return pkgJson.keywords?.includes('my-framework') ?? false
  },
  isSemiFrameworkPkgByName(pkgName) {
    return pkgName === 'my-framework-helpers' || undefined
  },
  isSemiFrameworkPkgByJson(pkgJson) {
    return !!(
      pkgJson.dependencies?.['my-framework'] ||
      pkgJson.peerDependencies?.['my-framework']
    )
  },
})
```

### Usage Example in Vite Plugin
```ts
export function myFrameworkPlugin() {
  return {
    name: 'vite-plugin-my-framework',
    async config(userConfig) {
      const { optimizeDeps, ssr } = await crawlFrameworkPkgs({
        root: userConfig.root ?? process.cwd(),
        isBuild: userConfig.build?.ssr != null,
        viteUserConfig: userConfig,
        isFrameworkPkgByJson: (pkg) => pkg.keywords?.includes('my-framework'),
      })
      return { optimizeDeps, ssr }
    },
  }
}
```
```

--------------------------------

### Crawl Framework Packages with Vitefu

Source: https://context7.com/bluwy/vitefu/llms.txt

Use `crawlFrameworkPkgs` within a Vite plugin's config hook to generate Vite configuration for framework-specific packages. It identifies framework packages by name or by inspecting their `package.json` and handles semi-framework packages. Respects existing user configurations.

```typescript
import { crawlFrameworkPkgs, searchForWorkspaceRoot } from 'vitefu'
// import { searchForWorkspaceRoot } from 'vite'

// Inside a Vite plugin's `config` or `configResolved` hook:
const result = await crawlFrameworkPkgs({
  // Required: absolute path to the project root (where package.json lives)
  root: process.cwd(),

  // Required: true during `vite build`, false during `vite dev`
  isBuild: false,

  // Optional: enables crawling devDependencies of private workspace packages
  workspaceRoot: searchForWorkspaceRoot(process.cwd()),

  // Optional: pass the user's vite config so existing optimizeDeps/ssr settings
  // are preserved and not overwritten
  viteUserConfig: userConfig,

  // Fast path: return true/false if you can decide from the name alone,
  // or undefined to fall through to isFrameworkPkgByJson
  isFrameworkPkgByName(pkgName) {
    if (pkgName === 'my-framework') return true
    if (pkgName.startsWith('@my-framework/')) return true
    return undefined
  },

  // Slow path: inspect package.json for definitive identification
  isFrameworkPkgByJson(pkgJson) {
    // e.g., packages that export a ".svelte" or ".framework" condition
    return pkgJson.keywords?.includes('my-framework') ?? false
  },

  // Semi-framework: doesn't export special files but imports from the framework
  isSemiFrameworkPkgByName(pkgName) {
    return pkgName === 'my-framework-helpers' || undefined
  },
  isSemiFrameworkPkgByJson(pkgJson) {
    return !!(
      pkgJson.dependencies?.['my-framework'] ||
      pkgJson.peerDependencies?.['my-framework']
    )
  },
})

// result shape:
// {
//   optimizeDeps: { include: [...], exclude: [...] },
//   ssr:          { noExternal: [...], external: [...] }
// }

// Merge into a Vite plugin:
export function myFrameworkPlugin() {
  return {
    name: 'vite-plugin-my-framework',
    async config(userConfig) {
      const { optimizeDeps, ssr } = await crawlFrameworkPkgs({
        root: userConfig.root ?? process.cwd(),
        isBuild: userConfig.build?.ssr != null,
        viteUserConfig: userConfig,
        isFrameworkPkgByJson: (pkg) => pkg.keywords?.includes('my-framework'),
      })
      return { optimizeDeps, ssr }
    },
  }
}
```

--------------------------------

### Find Dependency Package JSON Path

Source: https://context7.com/bluwy/vitefu/llms.txt

Use `findDepPkgJsonPath` to resolve the absolute path to a dependency's `package.json`. It supports Yarn PnP and mirrors Vite's resolution logic, including filesystem realpath checks.

```typescript
import { findDepPkgJsonPath } from 'vitefu'
import { readFile } from 'node:fs/promises'

// Locate the package.json of 'svelte' from the current working directory
const pkgJsonPath = await findDepPkgJsonPath('svelte', process.cwd())

if (pkgJsonPath) {
  const pkgJson = JSON.parse(await readFile(pkgJsonPath, 'utf8'))
  console.log(pkgJson.version) // e.g., "4.2.18"
} else {
  console.warn('svelte is not installed')
}

// Works for scoped packages too
const vuePkgPath = await findDepPkgJsonPath('@vue/runtime-core', process.cwd())
console.log(vuePkgPath)
// → /path/to/project/node_modules/@vue/runtime-core/package.json
```

--------------------------------

### findDepPkgJsonPath(dep, parent)

Source: https://context7.com/bluwy/vitefu/llms.txt

Resolves the absolute path to a dependency's `package.json` by traversing the `node_modules` directories upwards from a parent directory. Supports Yarn PnP and Vite's resolution logic.

```APIDOC
## findDepPkgJsonPath(dep, parent)

### Description
Resolves the absolute path to the `package.json` of a named dependency by walking up from `parent` through successive `node_modules` directories. Mirrors Vite's own resolution logic (including `node:fs` realpath to avoid quirks on Windows network drives) and transparently supports Yarn PnP environments.

### Parameters
#### Path Parameters
- **dep** (string) - Required - The name of the dependency to find.
- **parent** (string) - Required - The directory to start searching upwards from.

### Returns
- **string | null** - The absolute path to the `package.json` file, or `null` if not found.

### Request Example
```ts
import { findDepPkgJsonPath } from 'vitefu'
import { readFile } from 'node:fs/promises'

const pkgJsonPath = await findDepPkgJsonPath('svelte', process.cwd())

if (pkgJsonPath) {
  const pkgJson = JSON.parse(await readFile(pkgJsonPath, 'utf8'))
  console.log(pkgJson.version)
} else {
  console.warn('svelte is not installed')
}

const vuePkgPath = await findDepPkgJsonPath('@vue/runtime-core', process.cwd())
console.log(vuePkgPath)
// → /path/to/project/node_modules/@vue/runtime-core/package.json
```
```

--------------------------------

### findClosestPkgJsonPath

Source: https://context7.com/bluwy/vitefu/llms.txt

Walks upward from a given directory to find the nearest `package.json` file. It can optionally filter results using a synchronous or asynchronous predicate function. This is useful for locating project roots or specific ancestor packages in monorepos.

```APIDOC
## `findClosestPkgJsonPath(dir, predicate?)`

Walks upward from `dir` until it finds a `package.json` file, optionally filtering by a synchronous or asynchronous `predicate`. Correctly skips directory entries named `package.json` (only actual files are returned). Useful for locating the project root or a specific ancestor package in a monorepo.

### Parameters
#### Path Parameters
- **dir** (string) - Required - The directory to start searching from.
- **predicate** (function(string): (boolean | Promise<boolean>)) - Optional - A function that takes the path to a `package.json` file and returns `true` if it matches, `false` otherwise. Can be sync or async.

### Request Example
```ts
import { findClosestPkgJsonPath } from 'vitefu'

// Find the nearest package.json from a source file
const nearest = await findClosestPkgJsonPath('/project/src/components/Button.ts')
console.log(nearest) // → /project/src/package.json  (or /project/package.json)

// Walk upwards until we find the workspace root package
const workspaceRoot = await findClosestPkgJsonPath(
  '/project/packages/my-lib/src',
  async (pkgJsonPath) => {
    const json = JSON.parse(await readFile(pkgJsonPath, 'utf8'))
    return json.name === 'my-workspace-root'
  }
)
console.log(workspaceRoot) // → /project/package.json

// Safe with throwing predicates – thrown errors are treated as `false`
const safe = await findClosestPkgJsonPath('/project/src', (p) => {
  throw new Error('oops') // treated as false, search continues upward
})
```
```

--------------------------------

### Find Closest Package.json Path

Source: https://context7.com/bluwy/vitefu/llms.txt

Walks upward from a directory to find the nearest package.json file. Optionally filters by a predicate function. Useful for locating project roots or specific ancestor packages in monorepos.

```typescript
import { findClosestPkgJsonPath } from 'vitefu'
import { readFile } from 'node:fs/promises'

// 1. Find the nearest package.json from a source file
const nearest = await findClosestPkgJsonPath('/project/src/components/Button.ts')
console.log(nearest) // → /project/src/package.json  (or /project/package.json)

// 2. Walk upwards until we find the workspace root package
const workspaceRoot = await findClosestPkgJsonPath(
  '/project/packages/my-lib/src',
  async (pkgJsonPath) => {
    const json = JSON.parse(await readFile(pkgJsonPath, 'utf8'))
    return json.name === 'my-workspace-root'
  }
)
console.log(workspaceRoot) // → /project/package.json

// 3. Safe with throwing predicates – thrown errors are treated as `false`
const safe = await findClosestPkgJsonPath('/project/src', (p) => {
  throw new Error('oops') // treated as false, search continues upward
})
```

--------------------------------

### isDepExcluded

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks if a dependency is present in an `optimizeDeps.exclude` array. It supports exact matches and prefix matches (e.g., `"@scope/pkg/sub-path"` matches `"@scope/pkg"`). It also handles deep-include notation like `"framework > @scope/pkg"` by parsing out the dependency name.

```APIDOC
## `isDepExcluded(dep, optimizeDepsExclude)`

Synchronously checks whether `dep` (or its deep-include form like `"foo > bar"`) is covered by an existing `optimizeDeps.exclude` array. Handles both exact matches and prefix matches (`dep` starts with `excludedId + "/"`). Use this to filter out includes that the user has explicitly excluded.

### Parameters
#### Path Parameters
- **dep** (string) - Required - The dependency name to check.
- **optimizeDepsExclude** (string[]) - Required - The array of excluded dependency names.

### Request Example
```ts
import { isDepExcluded } from 'vitefu'

const userExclude = ['@scope/pkg', 'lodash']

isDepExcluded('@scope/pkg', userExclude)            // true  – exact match
isDepExcluded('@scope/pkg/sub-path', userExclude)   // true  – prefix match
isDepExcluded('framework > @scope/pkg', userExclude) // true  – deep-include parsed to @scope/pkg
isDepExcluded('axios', userExclude)                 // false

// Practical usage: filter crawled includes against user config
const includes = ['my-framework > cjs-dep', 'other-dep']
const filtered = includes.filter((dep) => !isDepExcluded(dep, userExclude))
```
```

--------------------------------

### pkgNeedsOptimization

Source: https://context7.com/bluwy/vitefu/llms.txt

Determines if a package should be included in Vite's `optimizeDeps.include` list. A package needs optimization if it's CommonJS-only, indicated by the absence of `module` or `exports` fields, or if its main entry point uses a `.js` or `.cjs` extension. ESM-first packages with an `exports` map are skipped.

```APIDOC
## `pkgNeedsOptimization(pkgJson, pkgJsonPath)`

Determines whether a package should be added to `optimizeDeps.include` so that Vite pre-bundles it into ESM. A package needs optimization when it is CJS-only: it has no `module` or `exports` field, its `main` entry (if present) uses a `.js` or `.cjs` extension, or it exposes an implicit `index.js` entry point. ESM-first packages with an `exports` map are skipped.

### Parameters
#### Path Parameters
- **pkgJson** (object) - Required - The parsed content of the `package.json` file.
- **pkgJsonPath** (string) - Required - The file path to the `package.json` file.

### Request Example
```ts
import { pkgNeedsOptimization, findDepPkgJsonPath } from 'vitefu'
import { readFile } from 'node:fs/promises'

async function checkDep(depName: string) {
  const pkgJsonPath = await findDepPkgJsonPath(depName, process.cwd())
  if (!pkgJsonPath) return

  const pkgJson = JSON.parse(await readFile(pkgJsonPath, 'utf8'))
  const needs = await pkgNeedsOptimization(pkgJson, pkgJsonPath)

  if (needs) {
    console.log(`${depName} is CJS – add to optimizeDeps.include`)
  } else {
    console.log(`${depName} is ESM-ready – no optimization needed`)
  }
}

await checkDep('lodash')        // true  – CJS, has implicit index.js
await checkDep('lodash-es')     // false – has `module` / `exports`
await checkDep('@sveltejs/kit') // false – ESM with exports map
```
```

--------------------------------

### Determine if Package Needs Vite Optimization

Source: https://context7.com/bluwy/vitefu/llms.txt

Checks if a package.json should be added to Vite's `optimizeDeps.include`. A package needs optimization if it's CJS-only (no 'module'/'exports', main uses .js/.cjs, or implicit index.js). ESM-first packages with an exports map are skipped.

```typescript
import { pkgNeedsOptimization, findDepPkgJsonPath } from 'vitefu'
import { readFile } from 'node:fs/promises'

async function checkDep(depName: string) {
  const pkgJsonPath = await findDepPkgJsonPath(depName, process.cwd())
  if (!pkgJsonPath) return

  const pkgJson = JSON.parse(await readFile(pkgJsonPath, 'utf8'))
  const needs = await pkgNeedsOptimization(pkgJson, pkgJsonPath)

  if (needs) {
    console.log(`${depName} is CJS – add to optimizeDeps.include`)
  } else {
    console.log(`${depName} is ESM-ready – no optimization needed`)
  }
}

await checkDep('lodash')        // true  – CJS, has implicit index.js
await checkDep('lodash-es')     // false – has `module` / `exports`
await checkDep('@sveltejs/kit') // false – ESM with exports map
```

--------------------------------

### isDepIncluded

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks if a dependency is represented in an `optimizeDeps.include` array. It correctly handles the deep-include notation (`"parent > child"`) by comparing only the child segment of the notation against the include list.

```APIDOC
## `isDepIncluded(dep, optimizeDepsInclude)`

Synchronously checks whether a dependency name is represented in an existing `optimizeDeps.include` array, accounting for the `"parent > child"` deep-include notation by comparing only the final segment.

### Parameters
#### Path Parameters
- **dep** (string) - Required - The dependency name to check.
- **optimizeDepsInclude** (string[]) - Required - The array of included dependency names.

### Request Example
```ts
import { isDepIncluded } from 'vitefu'

const userInclude = ['foo', 'parent > bar']

isDepIncluded('foo', userInclude)   // true
isDepIncluded('bar', userInclude)   // true  – matched via deep-include notation
isDepIncluded('baz', userInclude)   // false

// Use it to skip adding excludes for packages the user has forced to include:
const excludes = ['bar', 'qux']
const filtered = excludes.filter((dep) => !isDepIncluded(dep, userInclude))
// → ['qux']  ('bar' is kept by user, so we don't override)
```
```

--------------------------------

### isDepNoExternaled(dep, ssrNoExternal)

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks whether a dependency matches an existing ssr.noExternal configuration. It supports various formats for ssr.noExternal, including boolean true, string arrays, individual strings, RegExp instances, or mixed arrays of strings and RegExps.

```APIDOC
## `isDepNoExternaled(dep, ssrNoExternal)`

Synchronously checks whether `dep` matches an existing `ssr.noExternal` configuration. Supports `true` (all packages are noExternal), string arrays, individual strings, RegExp instances, or mixed arrays of strings and RegExps — mirroring all forms accepted by Vite's `ssr.noExternal` option.

```ts
import { isDepNoExternaled } from 'vitefu'

isDepNoExternaled('foo', true)                    // true  – all are noExternal
isDepNoExternaled('foo', ['foo', 'bar'])           // true
isDepNoExternaled('foo', /^foo/)                  // true
isDepNoExternaled('foo', ['bar', /^fo/])           // true
isDepNoExternaled('baz', ['foo', /^fo/])           // false

// Filter out packages the user has already set as noExternal before adding ssr.external:
const externalsToAdd = ['some-dep', 'framework-dep']
const userNoExternal = [/^@my-framework\]
const safeExternals = externalsToAdd.filter(
  (dep) => !isDepNoExternaled(dep, userNoExternal)
)
```
```

--------------------------------

### Check if Dependency is Excluded from Vite Optimization

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks if a dependency is present in an `optimizeDeps.exclude` array. Handles exact and prefix matches (e.g., 'pkg/sub-path'). Useful for filtering includes against user exclusions.

```typescript
import { isDepExcluded } from 'vitefu'

const userExclude = ['@scope/pkg', 'lodash']

isDepExcluded('@scope/pkg', userExclude)            // true  – exact match
isDepExcluded('@scope/pkg/sub-path', userExclude)   // true  – prefix match
isDepExcluded('framework > @scope/pkg', userExclude) // true  – deep-include parsed to @scope/pkg
isDepExcluded('axios', userExclude)                 // false

// Practical usage: filter crawled includes against user config
const includes = ['my-framework > cjs-dep', 'other-dep']
const filtered = includes.filter((dep) => !isDepExcluded(dep, userExclude))
```

--------------------------------

### Check if Dependency is Included in Vite Optimization

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks if a dependency is present in an `optimizeDeps.include` array. Accounts for deep-include notation ('parent > child') by comparing only the final segment. Use to skip adding excludes for packages the user has forced to include.

```typescript
import { isDepIncluded } from 'vitefu'

const userInclude = ['foo', 'parent > bar']

isDepIncluded('foo', userInclude)   // true
isDepIncluded('bar', userInclude)   // true  – matched via deep-include notation
isDepIncluded('baz', userInclude)   // false

// Use it to skip adding excludes for packages the user has forced to include:
const excludes = ['bar', 'qux']
const filtered = excludes.filter((dep) => !isDepIncluded(dep, userInclude))
// → ['qux']  ('bar' is kept by user, so we don't override)
```

--------------------------------

### isDepExternaled(dep, ssrExternal)

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks whether a dependency is listed in an existing ssr.external array. If ssr.external is true (Vite 6 linked-dependency behavior), this function returns false as that flag doesn't represent explicit per-package externalization.

```APIDOC
## `isDepExternaled(dep, ssrExternal)`

Synchronously checks whether `dep` is listed in an existing `ssr.external` array. When `ssr.external` is `true` (Vite 6 linked-dependency behavior), this function returns `false` because that flag does not represent an explicit per-package externalization.

```ts
import { isDepExternaled } from 'vitefu'

isDepExternaled('foo', ['foo', 'bar'])  // true
isDepExternaled('baz', ['foo', 'bar'])  // false
isDepExternaled('foo', true)            // false – true is not explicit per-package

// Filter out packages already externalized before adding to ssr.noExternal:
const noExternalsToAdd = ['my-framework', 'peer-lib']
const userExternal = ['peer-lib']
const safeNoExternals = noExternalsToAdd.filter(
  (dep) => !isDepExternaled(dep, userExternal)
)
// → ['my-framework']
```
```

--------------------------------

### Check if Dependency is No Externaled

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks if a dependency matches the `ssr.noExternal` configuration. Supports various formats including booleans, string arrays, strings, and RegExps.

```typescript
import { isDepNoExternaled } from 'vitefu'

isDepNoExternaled('foo', true)                    // true  – all are noExternal
isDepNoExternaled('foo', ['foo', 'bar'])           // true
isDepNoExternaled('foo', /^foo/)                  // true
isDepNoExternaled('foo', ['bar', /^fo/])           // true
isDepNoExternaled('baz', ['foo', /^fo/])           // false

// Filter out packages the user has already set as noExternal before adding ssr.external:
const externalsToAdd = ['some-dep', 'framework-dep']
const userNoExternal = [/^@my-framework\]
const safeExternals = externalsToAdd.filter(
  (dep) => !isDepNoExternaled(dep, userNoExternal)
)
```

--------------------------------

### Check if Dependency is Externaled

Source: https://context7.com/bluwy/vitefu/llms.txt

Synchronously checks if a dependency is listed in the `ssr.external` array. Returns `false` if `ssr.external` is `true` as this does not represent explicit per-package externalization.

```typescript
import { isDepExternaled } from 'vitefu'

isDepExternaled('foo', ['foo', 'bar'])  // true
isDepExternaled('baz', ['foo', 'bar'])  // false
isDepExternaled('foo', true)            // false – true is not explicit per-package

// Filter out packages already externalized before adding to ssr.noExternal:
const noExternalsToAdd = ['my-framework', 'peer-lib']
const userExternal = ['peer-lib']
const safeNoExternals = noExternalsToAdd.filter(
  (dep) => !isDepExternaled(dep, userExternal)
)
// → ['my-framework']
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.