📎 Platform Imports

Jaspr normally runs both on the server and client. The same code will be compiled twice for the server and the web. Most of the time this isn't an issue, however sometimes you might want to use a package or library that is only supported on one side, like:

• dart:html will only work on the client,
• dart:io will only work on the server.

When you want to use such a library in your project, you would have to resort to conditional imports, which are quite cumbersome to use since you have to create multiple files and stub everything you want to use.

Jaspr can do this for you using the @Import annotation. Say you have the following component:

import 'dart:html' show window;

import 'package:jaspr/jaspr.dart';

class App extends StatelessComponent {
  @override
  Iterable<Component> build(BuildContext context) sync* {
    if (kIsWeb) {
      window.alert('Hi Jaspr');
    }
    yield DomComponent(
      tag: 'p',
      child: Text('Hello World'),
    );
  }
}

This component wants to show an alert when build, but only on web. We can correctly use the kIsWeb constant to check the platform during runtime, but this example would still lead to a compile time error when running on the server - because dart:html is unsupported there.

With jasprs platform-specific imports you can change the code to this:

@Import.onWeb('dart:html', show: [#window])
import 'app.imports.dart';

import 'package:jaspr/jaspr.dart';

class App extends StatelessComponent {
  @override
  Iterable<Component> build(BuildContext context) sync* {
    if (kIsWeb) {
      window.alert('Hi Jaspr');
    }
    yield DomComponent(
      tag: 'p',
      child: Text('Hello World'),
    );
  }
}

This will auto-generate:

• the app.imports.dart file
• conditional imports for dart:html on the web
• stubs on the server.

You can extend this to multiple imports and mix web and server imports like this:

@Import.onWeb('dart:html', show: [#window])
@Import.onWeb('package:some_js_package', show: [#someMember])
@Import.onServer('dart:io', show: [#Platform])
import 'app.imports.dart';

The show list must contain all the variables and types you want to access in your code, similar to the import ... show ...; syntax. Here each item in the list must be a symbol starting with #.