Fliplet.require

Fliplet.require

Fliplet.require and its Fliplet.require.lazy family give you two ways to load scripts and stylesheets at runtime: through the bootstrap gate (blocking app startup until assets are ready) or on demand after the app is already running.

Two-tier model

Fliplet’s runtime has two distinct loading tiers:

  • Bootstrap gate (Fliplet.require) — assets declared here must finish loading before the plugins-ready promise resolves. The app does not start rendering until they are done. Use this for foundational libraries your entire app depends on.
  • On-demand (Fliplet.require.lazy and family) — assets load without touching the bootstrap gate. Each call returns its own Promise and the rest of the app continues running. Use this for optional features, heavy third-party libraries, or anything you want to defer until a user action.

Fliplet.require

Loads one or more scripts after plugins-ready and, when they have finished loading, resolves the internal bootstrap gate so the app can proceed.

Signature

Fliplet.require(scripts)
Parameter Type Description
scripts String \| Array<String> A single script URL or an array of script URLs to load in series.

The function does not return a Promise. It fires-and-forgets — the runtime resolves the bootstrap gate internally once all scripts have loaded.

Example

// Load a single script before the app starts
Fliplet.require('https://cdn.example.com/chart.min.js');

// Load multiple scripts in series
Fliplet.require([
  'https://cdn.example.com/moment.min.js',
  'https://cdn.example.com/moment-timezone.min.js'
]);

Fliplet.require.lazy

Loads a single dependency on demand without blocking the bootstrap gate. Returns a Promise that resolves when the asset is ready. Input can be a registered name, a raw URL, or a media file ID.

Signature

Fliplet.require.lazy(input, options)
Parameter Type Description
input String \| Number Registered dependency name, a URL (http/https/protocol-relative), or a numeric media file ID.
options Object Optional. Supported key: responseType (used when input is a media file ID).

By registered name

Dependencies registered in the app bundle under Fliplet.Env.get('dependencies').lazy can be loaded by name. The runtime resolves the correct URL for the current environment (web or native) automatically.

If the named dependency has transitive deps (dep.chain is set), calling .lazy() rejects with an error instructing you to use .chain() instead.

Fliplet.require.lazy('signature-pad').then(function() {
  // SignaturePad is now available on window
  var pad = new SignaturePad(document.getElementById('canvas'));
});

By URL

Pass any http://, https://, or protocol-relative (//) URL. The runtime infers the asset type from the file extension — .css triggers loadStylesheet, everything else triggers loadScript. Duplicate URLs are deduped: a second call with the same URL resolves immediately without a second network request.

// Load a JavaScript library
Fliplet.require.lazy('https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js').then(function() {
  var ctx = document.getElementById('myChart').getContext('2d');
  new Chart(ctx, { type: 'bar', data: { labels: ['A', 'B'], datasets: [{ data: [1, 2] }] } });
});

// Load a stylesheet
Fliplet.require.lazy('https://cdn.example.com/theme.css').then(function() {
  console.log('Stylesheet applied');
});

By media file ID

Pass a numeric Fliplet media file ID. The runtime fetches the file’s metadata to determine its content type, then loads it as a script, stylesheet, or raw content accordingly. Requires fliplet-media to be loaded.

Pass { responseType: 'json' } (or any other responseType) to skip content-type detection and return the raw file contents directly via Fliplet.Media.getContents.

// Load by media file ID — content type detected automatically
Fliplet.require.lazy(123456).then(function() {
  console.log('Media file loaded');
});

// Fetch a JSON media file's contents directly
Fliplet.require.lazy(123456, { responseType: 'json' }).then(function(data) {
  console.log('JSON data:', data);
});

Fliplet.require.lazy.chain

Loads a registered dependency that has transitive dependencies (dep.chain), walking the chain in serial order. This is the required path for any named dep that .lazy() rejects on — the error message from .lazy() tells you to call .chain().

The result per name is memoized in chainPromises{}, so repeated calls within the same session resolve from the cache without re-loading.

For named deps that have no chain, .chain() falls back to Fliplet.require.lazy(name) automatically.

Signature

Fliplet.require.lazy.chain(name)
Parameter Type Description
name String Registered lazy dependency name.

Returns a Promise that resolves when the named dependency and all its transitive deps have loaded.

Example

// 'select2' is registered with a dep.chain (jQuery must load first)
Fliplet.require.lazy.chain('select2').then(function() {
  $('#my-select').select2();
});

Inspect the registry

Fliplet.require.lazy.list()

Returns an array of all registered lazy dependency names from Fliplet.Env.get('dependencies').lazy.

var names = Fliplet.require.lazy.list();
console.log(names); // e.g. ['signature-pad', 'select2', 'chart-js']

Fliplet.require.lazy.get(name)

Returns the resolved URL for a named dependency without loading it. On native apps, returns dep.path; on web, returns dep.url. Returns null if the name is not registered.

var url = Fliplet.require.lazy.get('signature-pad');
console.log(url); // 'https://cdn.fliplet.com/libs/signature-pad/1.5.3/signature_pad.min.js'

Error handling

Fliplet.require.lazy (and .chain) rejects under these conditions:

  • Not a string or number — input type is invalid; message: Fliplet.require.lazy() expects a string or number.
  • Named dep with a chain — the dep is registered with transitive deps; message instructs use of .chain().
  • Named dep with no URL — the dep record has neither dep.path (native) nor dep.url (web).
  • Unrecognized string that is not a URL — input is not a registered name and not an http://, https://, or // URL; message lists all available registered names.
  • Unregistered name passed to .chain() — name is not in the lazy deps map; message lists all available registered names.
  • Media file loaded without fliplet-media — Fliplet.Media is not defined when a numeric ID is passed; message: Fliplet.Media is not available. Ensure fliplet-media is loaded.

See also