Block dynamic imports in v8 isolate Convex files at deploy time

[ghandic]

Summary

• Add deploy-time validation that rejects import() expressions in Convex files that don't have a "use node" directive. Previously this was only caught at runtime in the V8 isolate, leading to a bad DX.
• The check runs during bundling in entryPointsByEnvironment(), before esbuild, using @babel/parser AST analysis with a fast string pre-check.
• Test files (.test.ts, .spec.ts) are already excluded from entry points by existing bundler logic and are unaffected.

Test plan

• Added unit tests for hasDynamicImport() covering: top-level imports, nested in functions, template literals, TypeScript, static-only imports, comments, and string literals.
• Added integration tests verifying entryPointsByEnvironment() rejects isolate files with dynamic imports and allows them in "use node" files.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ianmacartney]

Some libraries use this to dynamically pull in the right files - and I believe esbuild tries to detect these and bundle them in. What issue were you seeing that led you to suggest this change?

…

On Thu, Feb 26, 2026 at 1:53 PM Andy Challis ***@***.***> wrote: Summary - Add deploy-time validation that rejects import() expressions in Convex files that don't have a "use node" directive. Previously this was only caught at runtime in the V8 isolate, leading to a bad DX. - The check runs during bundling in entryPointsByEnvironment(), before esbuild, using @babel/parser AST analysis with a fast string pre-check. - Test files (.test.ts, .spec.ts) are already excluded from entry points by existing bundler logic and are unaffected. Test plan - Added unit tests for hasDynamicImport() covering: top-level imports, nested in functions, template literals, TypeScript, static-only imports, comments, and string literals. - Added integration tests verifying entryPointsByEnvironment() rejects isolate files with dynamic imports and allows them in "use node" files. ------------------------------ By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice. ------------------------------ You can view, comment on, or merge this pull request online at: #379 Commit Summary - 5dec8c6 <5dec8c6> catch dynamic imports before deployment File Changes (4 files <https://github.com/get-convex/convex-backend/pull/379/files>) - *M* npm-packages/convex/src/bundler/index.test.ts <https://github.com/get-convex/convex-backend/pull/379/files#diff-e46b18684d1cde4b89b1843f3189953d38365d6a96ba77c05ae9d4544b49d067> (101) - *M* npm-packages/convex/src/bundler/index.ts <https://github.com/get-convex/convex-backend/pull/379/files#diff-3374941a06f66c232634e599f5072cb443a429389d4c937c8db8164eb7cd971d> (52) - *A* npm-packages/convex/src/bundler/test_fixtures/js/project_with_dynamic_import/actions.js <https://github.com/get-convex/convex-backend/pull/379/files#diff-c09fa6914222d0cea6e62d7cdb86e92f8c77eec34b0d4f78a1437bcda8914b1a> (4) - *A* npm-packages/convex/src/bundler/test_fixtures/js/project_with_dynamic_import_use_node/actions.js <https://github.com/get-convex/convex-backend/pull/379/files#diff-c27a8f400de5ee3df4376bde469516a2a9ec3c5b4a8f33c359ef78b9c990552f> (6) Patch Links: - https://github.com/get-convex/convex-backend/pull/379.patch - https://github.com/get-convex/convex-backend/pull/379.diff — Reply to this email directly, view it on GitHub <#379>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW4SWEPDI4A3XA5FKL34N5TLXAVCNFSM6AAAAACWBB7N2CVHI2DSMVQWIX3LMV43ASLTON2WKOZTHE4TOOJUGIYDKMI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[ghandic]

Dynamic imports fail at runtime on convex but don't get caught at build. I've had agents add this in and I normally find it quickly before it matters but people in discord have had similar issues. If it's blocked at runtime why not build time ?

[ianmacartney]

I wasn't aware the dynamic imports always failed - I thought they'd succeed if the file is bundled. Will this add significant latency if they have 30MB of functions, say? Any benchmarks on the bundle latency or sense of the impact?

[ghandic]

Should be low impact as it does a string match first and only runs if there's import(

[ianmacartney]

It both works and doesn't work 😅

Building udf test bundle
  Error: Failed to run convex deploy:

  - Deploying to http://127.0.0.1:8000.../

  ✖ Dynamic import (`import()`) is not allowed in "import_tests.ts" because it does not have a "use node" directive. Dynamic imports are only supported in Node.js actions. Add "use node" at the top of the file if this is a Node.js action, or replace the dynamic import with a static import.


  Stack backtrace:
     0: anyhow::error::<impl anyhow::Error>::msg
     1: build_script_build::write_udf_test_bundle
     2: build_script_build::main
     3: core::ops::function::FnOnce::call_once
     4: std::sys::backtrace::__rust_begin_short_backtrace
     5: std::rt::lang_start::{{closure}}
     6: core::ops::function::impls::<impl core::ops::function::FnOnce<A> for &F>::call_once
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/core/src/ops/function.rs:284:21
     7: std::panicking::catch_unwind::do_call
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/panicking.rs:589:40
     8: std::panicking::catch_unwind
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/panicking.rs:552:19
     9: std::panic::catch_unwind
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/panic.rs:359:14
    10: std::rt::lang_start_internal::{{closure}}
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/rt.rs:175:24
    11: std::panicking::catch_unwind::do_call
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/panicking.rs:589:40
    12: std::panicking::catch_unwind
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/panicking.rs:552:19
    13: std::panic::catch_unwind
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/panic.rs:359:14
    14: std::rt::lang_start_internal
               at /rustc/bdaba05a953eb5abeba0011cdda2560d157aed2e/library/std/src/rt.rs:171:5
    15: std::rt::lang_start
    16: main
    17: <unknown>
    18: __libc_start_main
    19: _start
[Clippy] Clippy error
Traceback (most recent call last):
  File "/opt/actions-runner/_work/convex/convex/./scripts/run_rust_lint.py", line 356, in <module>
    run_checks(parse_args())
    ~~~~~~~~~~^^^^^^^^^^^^^^
  File "/opt/actions-runner/_work/convex/convex/./scripts/run_rust_lint.py", line 313, in run_checks
    run_check(lambda: run_clippy(args), "Clippy", violations, fail_fast)
    ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/actions-runner/_work/convex/convex/./scripts/run_rust_lint.py", line 274, in run_check
    check()
    ~~~~~^^
  File "/opt/actions-runner/_work/convex/convex/./scripts/run_rust_lint.py", line 313, in <lambda>
    run_check(lambda: run_clippy(args), "Clippy", violations, fail_fast)
                      ~~~~~~~~~~^^^^^^
  File "/opt/actions-runner/_work/convex/convex/./scripts/run_rust_lint.py", line 267, in run_clippy
    raise Exception("Clippy error")

this is failing for this file that currently tests that dynamic imports work (perhaps only if they're explicitly imported elsewhere?):

import * as helpersStatic from "./helpers";

export const dynamicImport = action({
  args: {},
  handler: async () => {
    const helpers = await import("./helpers");
    assert.strictEqual(helpers.fibonacci(6), 8.0);
    // The `import * as helpersStatic` repackages the namespace object, so we
    // can't assert helpersStatic === helpers, but we can check that the module
    // was not re-evaluated by checking equality of a field.
    assert.strictEqual(helpersStatic.fibonacci, helpers.fibonacci);
    const helpersAgain = await import("./helpers");
    assert.strictEqual(helpers, helpersAgain);
    const helpersDifferentPath = await import("./helpers");
    assert.strictEqual(helpers, helpersDifferentPath);
  },
});