> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouim.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Bundler Configuration

> Configure Vite, Webpack, or Next.js to work with logto-authkit

logto-authkit provides pre-configured bundler settings to resolve common issues with the `jose` library and optimize dependencies.

## Why Bundler Configuration?

The underlying Logto SDK uses the `jose` library for JWT handling, which can cause bundling issues in some environments. logto-authkit provides ready-to-use configurations that:

* Resolve `jose` library compatibility issues
* Optimize dependency bundling
* Ensure proper module resolution

## Vite Configuration

<Warning>
  When editing a Vite config or other build-time script, import directly from the `bundler-config` subpath. This avoids executing the main library bundle (which pulls in React and may cause issues during Node startup).
</Warning>

```javascript vite.config.js theme={null}
import { viteConfig } from '@ouim/logto-authkit/bundler-config'

export default {
  ...viteConfig,
  // your other config
}
```

### What's Included

The Vite configuration provides:

```javascript theme={null}
{
  optimizeDeps: {
    include: ['@logto/react', '@ouim/better-logto-react'],
  },
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```

## Webpack Configuration

```javascript webpack.config.js theme={null}
import { webpackConfig } from '@ouim/logto-authkit'

module.exports = {
  ...webpackConfig,
  // your other config
}
```

### What's Included

The Webpack configuration provides:

```javascript theme={null}
{
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```

## Next.js Configuration

```javascript next.config.js theme={null}
import { nextjsConfig } from '@ouim/logto-authkit'

module.exports = {
  ...nextjsConfig,
  // your other config
}
```

### What's Included

The Next.js configuration provides the same alias configuration as Webpack:

```javascript theme={null}
{
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```

## Custom Configuration

If you need more control or want to integrate the configuration differently, you can use the `getBundlerConfig` helper:

```javascript theme={null}
import { getBundlerConfig } from '@ouim/logto-authkit/bundler-config'

// Get configuration for specific bundler
const viteConfig = getBundlerConfig('vite')
const webpackConfig = getBundlerConfig('webpack')
const nextConfig = getBundlerConfig('nextjs')
```

### Parameters

The `getBundlerConfig` function accepts one parameter:

<ParamField path="bundler" type="'vite' | 'webpack' | 'nextjs'" default="'vite'">
  The bundler type to get configuration for
</ParamField>

### Merging with Existing Config

You can merge the provided configuration with your existing setup:

```javascript vite.config.js theme={null}
import { getBundlerConfig } from '@ouim/logto-authkit/bundler-config'
import { defineConfig } from 'vite'

const logtoConfig = getBundlerConfig('vite')

export default defineConfig({
  // Merge optimize deps
  optimizeDeps: {
    ...logtoConfig.optimizeDeps,
    include: [
      ...logtoConfig.optimizeDeps.include,
      'your-other-deps',
    ],
  },
  // Merge resolve aliases
  resolve: {
    ...logtoConfig.resolve,
    alias: {
      ...logtoConfig.resolve.alias,
      '@': '/src',
    },
  },
  // Your other config
  plugins: [...],
})
```

<Tip>
  The bundler configuration is minimal and designed to be easily merged with your existing setup. It only modifies what's necessary for logto-authkit to work properly.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Module not found: jose">
    Make sure you've applied the bundler configuration. The `jose` alias resolves to the CommonJS distribution which is more compatible with bundlers.
  </Accordion>

  <Accordion title="React errors during build">
    If you're importing from the main package in your build config, switch to importing from `@ouim/logto-authkit/bundler-config` instead. This avoids loading React during the build process.
  </Accordion>

  <Accordion title="Vite optimization errors">
    If you see errors about pre-bundling dependencies, make sure the `optimizeDeps.include` array includes both `@logto/react` and `@ouim/better-logto-react`.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Guest Mode" icon="user" href="/logto-authkit/configuration/guest-mode">
    Learn how to enable guest mode for unauthenticated users
  </Card>

  <Card title="Custom Navigation" icon="route" href="/logto-authkit/configuration/custom-navigation">
    Set up custom navigation with your router
  </Card>
</CardGroup>