@magek/core CLI Dependency Problem

[javiertoledo]

Summary

The @magek/core package has a direct dependency on @oclif/core which prevents the package from being used in bundled environments like Next.js, Vite, or any frontend bundler.

Problem Description

When attempting to build a Next.js application that imports MagekGraphQLDispatcher from @magek/core, the build fails with the following errors:

Module not found: Can't resolve './ROOT/node_modules/@oclif/core/package.json'

Module not found: Can't resolve 'ts-node'
  at ./node_modules/@oclif/core/lib/config/ts-path.js:109:24

Root Cause

In /packages/core/src/magek.ts, line 26:

import { Errors, Config } from '@oclif/core'

This import is used for CLI command functionality in the Magek.start() method (lines 91-108), specifically for running injectable CLI commands.

Import Chain

app/api/graphql/route.ts
  → @magek/core/dist/index.js
    → @magek/core/dist/magek.js
      → @oclif/core (CLI framework)
        → ts-node (TypeScript runtime)

Impact

1. Next.js Applications: Cannot use @magek/core in Next.js API routes without workarounds
2. Vercel Deployments: Serverless functions cannot bundle @magek/core
3. Frontend Bundlers: Any bundler (webpack, vite, esbuild) will fail to process the package
4. Tree-shaking: Even though MagekGraphQLDispatcher doesn't use CLI functionality, the import graph pulls in all CLI dependencies

Workaround (Current)

For Next.js applications, the workaround is to externalize the problematic packages in next.config.ts:

const nextConfig: NextConfig = {
  serverExternalPackages: [
    '@oclif/core',
    'ts-node',
  ],
};

Limitations of this workaround:

• Only works for server-side code
• Requires the packages to be installed even if not used
• May cause issues in production deployments where these packages aren't available
• Not a viable solution for edge runtimes

Additional Notes

The CLI functionality (runInjectableCommands) is only triggered when:

1. process.env['MAGEK_CLI_HOOK'] equals 'true'
2. The application is started via Magek.start()

For serverless deployments using MagekGraphQLDispatcher directly, this CLI code path is never executed, yet the dependencies are still required at bundle time.

References

• @magek/core source: /packages/core/src/magek.ts
• Issue occurs at: Line 26 (import { Errors, Config } from '@oclif/core')
• CLI execution: Lines 73-88, 91-108