jaspr-js-interop

Rules for JS Interop

Dart makes accessing JavaScript simple using modern js_interop. Since Jaspr applications can be compiled to JavaScript or WebAssembly, utilizing Dart's explicit js_interop mechanism is required when you need to interface with raw JS variables, functions, or libraries.

1. Import Strategy

• Rule 1: In server or static mode, you MUST ALWAYS import package:universal_web/js_interop.dart. It acts as a safe stub during server-side processing without breaking compilation.
• Rule 2: In server or static mode, you MUST wrap any JS Interop execution in an if (kIsWeb) { ... } block to avoid throwing exceptions on the server during pre-rendering.
• Rule 3: In client mode, you can directly import dart:js_interop.
• Rule 4: For standard browser APIs (like window.innerHeight, document, DOM nodes), use package:universal_web/web.dart (or package:web/web.dart in client mode) instead of manually creating js_interop wrappers.

Usage Examples

Top Level Functions

To bind directly to a globally available JS function or object, use @JS():