xtal-fetch

library0.0.108jsnpmunverified

Vanilla web component wrapper around the native fetch API, inspired by Polymer's iron-ajax but with zero legacy dependencies and full ES6 module support. Current stable version is 0.0.108, with frequent updates. Key differentiators: lightweight (~2KB minzipped), works with any framework or no framework, supports Polymer-style template bindings, debouncing, base URL via link rel=preconnect, and a lite variant for minimal overhead. Breaks down into three subcomponents (xtal-fetch-lite, xtal-fetch, xtal-fetch.js) to reduce bundle size. Ships TypeScript types.

development

npm install xtal-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · XTAL-FETCH

xtal-fetch

developmentjavascriptv0.0.108

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

xtal-fetch

✓ import 'xtal-fetch/xtal-fetch.js';

✗ import XtalFetch from 'xtal-fetch';

Web component uses side-effect import; no default or named export exists. Use the .js extension for the full component.

xtal-fetch-lite

✓ import 'xtal-fetch/xtal-fetch-lite.js';

✗ const xtalFetch = require('xtal-fetch');

For lite variant (no error handling). Only use side-effect import.

xtal-fetch.js (UMD)

✓ <script src="https://unpkg.com/xtal-fetch@0.0.97/xtal-fetch.js?module"></script>

✗ <script src="xtal-fetch.js"></script>

Use ?module for ES module support in browsers. For legacy browsers, use the full .js file without ?module, but this is deprecated.

CustomElements

✓ customElements.define('xtal-fetch', XtalFetch);

✗ customElements.define('xtal-fetch', XtalFetch); // Not needed, auto-registered

The component auto-registers itself; manual define may conflict. Only needed if you must change the tag name.

Shows basic usage: import via side-effect, set attributes for fetch request, and listen for result-changed event to access data.

import 'xtal-fetch/xtal-fetch.js'; // HTML usage const el = document.createElement('xtal-fetch'); el.setAttribute('fetch', ''); el.setAttribute('href', 'https://api.example.com/data'); el.setAttribute('as', 'json'); document.body.appendChild(el); // Listen for results el.addEventListener('result-changed', (e) => { console.log('Fetched data:', e.detail.value); }); // Or use with template binding (e.g., Polymer) // <xtal-fetch fetch="[[binding]]" href="/api/[[binding]]" as="json"></xtal-fetch>

Debug

Known issues

gotchaThe 'fetch' attribute must be present for the request to fire; omitting it prevents any request.

fix

Always include fetch attribute (or set .fetch property to truthy) on the element.

affects: >=0.0.0

gotchaThe component auto-registers the custom element. Manually calling customElements.define may cause a DOMException if the tag is already registered.

fix

Do not manually define the element; rely on side-effect import.

affects: >=0.0.0

deprecatedUsing the .js file without ?module for ES module is deprecated; the module pattern is preferred.

fix

Use import or script with type=module.

affects: >=0.0.97

gotchaFor lite variant (xtal-fetch-lite), error handling is not supported; failed requests will silently fail.

fix

Use the full xtal-fetch or attach an error event listener if using lite.

affects: >=0.0.0

gotchaThe 'disable' property prevents requests even if 'fetch' is true; tie-breaker logic prioritizes disable.

fix

Ensure disable is falsy when intending to make requests.

affects: >=0.0.0

breakingChanges between minor versions may affect attribute names or events (e.g., 'value-changed' vs 'result-changed'); check release notes.

fix

Use version locking or test before upgrading.

affects: <0.0.97

Errors

Common errors & fixes

Uncaught TypeError: Failed to execute 'define' on 'CustomElementRegistry': the name 'xtal-fetch' has already been used with this registry

Attempting to manually define the custom element after import auto-registers it.

fix

Remove customElements.define('xtal-fetch', ...) call. The component auto-registers.

No 'fetch' attribute set, request not made.

Missing the required 'fetch' attribute or property on the element.

fix

Add fetch attribute: <xtal-fetch fetch href="..."> or set element.fetch = true.

TypeError: Cannot read properties of undefined (reading 'value')

Attempting to access e.detail.value on a result-changed event that wasn't fired or custom event detail isn't set.

fix

Ensure the event listener is attached after the element is connected to DOM and request completed. Check that 'as' attribute is correctly set.

404 Not Found when using base-link-id

baseLinkId not pointing to a valid <link> element with href attribute.

fix

Ensure there is a <link rel="preconnect" id="myBase" href="https://api.example.com/"> in the document head.

Script error for: xtal-fetch.js (line 0)

Loading the UMD script incorrectly (e.g., missing ?module or wrong path).

fix

Use correct import: import 'xtal-fetch/xtal-fetch.js'; for ES modules.

Upgrade

Version history

0.0.108latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

34 hits · last 30 days

node

Resources

githubhttps://github.com/bahrus/xtal-fetch ↗

packagextal-fetch ↗

homepagehttps://github.com/bahrus/xtal-fetch#readme ↗