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

# Next.js Setup

> Configure Next.js to work with MagenX404

## Overview

MagenX404 publishes TypeScript source files, which requires Next.js to be configured to transpile the package.

## Quick Setup

Add this to your `next.config.js` or `next.config.mjs`:

<CodeGroup>
  ```javascript next.config.js theme={null}
  /** @type {import('next').NextConfig} */
  const nextConfig = {
    transpilePackages: ["magenx404"],
  };

  export default nextConfig;
  ```

  ```javascript next.config.mjs theme={null}
  /** @type {import('next').NextConfig} */
  const nextConfig = {
    transpilePackages: ["magenx404"],
  };

  export default nextConfig;
  ```
</CodeGroup>

## Next.js 13+ (App Router)

The above configuration works for Next.js 13+ with the App Router. No additional setup needed.

## Next.js 12 (Pages Router)

For Next.js 12, use this webpack configuration:

```javascript theme={null}
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    config.resolve.extensionAlias = {
      ".js": [".ts", ".tsx", ".js", ".jsx"],
      ".jsx": [".tsx", ".jsx"],
    };
    return config;
  },
};

module.exports = nextConfig;
```

## TypeScript Configuration

Make sure your `tsconfig.json` includes the package:

```json theme={null}
{
  "compilerOptions": {
    // ... your config
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    "node_modules/magenx404/**/*"
  ]
}
```

## Verification

After configuration:

1. **Restart your Next.js dev server:**

   ```bash theme={null}
   npm run dev
   ```

2. **Test the import:**

   ```typescript theme={null}
   import { X404Blacklist } from "magenx404/blacklist";
   ```

3. **If you see errors, clear the cache:**
   ```bash theme={null}
   rm -rf .next
   npm run dev
   ```

## Using in Client Components

Since MagenX404 uses browser APIs (wallet connections, localStorage), you must use it in Client Components:

```typescript theme={null}
"use client";

import { X404Blacklist } from "magenx404/blacklist";

export function AuthComponent() {
  // Your component code
}
```

<Warning>
  The `"use client"` directive is required when using MagenX404 features in
  Next.js App Router components.
</Warning>

## Using in Server Components

You cannot directly use MagenX404 features in Server Components since they require browser APIs. However, you can:

1. Create a Client Component wrapper
2. Use the Client Component in your Server Component

```typescript theme={null}
// app/page.tsx (Server Component)
import { AuthButton } from "./components/AuthButton";

export default function Page() {
  return <AuthButton />;
}
```

```typescript theme={null}
// components/AuthButton.tsx (Client Component)
"use client";

import { X404Blacklist } from "magenx404/blacklist";

export function AuthButton() {
  // Your authentication logic
}
```

## Troubleshooting

### "Module not found" errors

1. **Verify `transpilePackages` is configured:**

   ```javascript theme={null}
   transpilePackages: ["magenx404"];
   ```

2. **Restart the dev server:**

   ```bash theme={null}
   # Stop the server (Ctrl+C)
   npm run dev
   ```

3. **Clear Next.js cache:**

   ```bash theme={null}
   rm -rf .next
   ```

4. **Reinstall the package:**
   ```bash theme={null}
   rm -rf node_modules/magenx404
   npm install
   ```

### Type errors

1. **Check `tsconfig.json` includes the package:**

   ```json theme={null}
   {
     "include": ["node_modules/magenx404/**/*"]
   }
   ```

2. **Verify TypeScript can find types:**
   ```typescript theme={null}
   import type { X404AuthResult } from "magenx404";
   ```

### Build errors

1. **Update Next.js to latest version:**

   ```bash theme={null}
   npm install next@latest
   ```

2. **Ensure TypeScript version is compatible:**
   ```bash theme={null}
   npm install typescript@latest
   ```

## Alternative: next-transpile-modules (Legacy)

If the above doesn't work, you can use `next-transpile-modules`:

```bash theme={null}
npm install --save-dev next-transpile-modules
```

```javascript theme={null}
const withTM = require("next-transpile-modules")(["magenx404"]);

module.exports = withTM({
  // your other Next.js config
});
```

<Note>
  This is a legacy approach. The `transpilePackages` option is preferred for
  Next.js 13+.
</Note>

## Next Steps

<Card title="Quick Start" icon="rocket" href="/quickstart">
  Start using MagenX404 in your Next.js app
</Card>

<Card title="Features" icon="list" href="/features/blacklist">
  Explore available authentication features
</Card>