{"id":48920,"library":"piral-fetch","title":"Piral Fetch","description":"Plugin for Piral that provides a standardized fetch API for pilets (microfrontends), with automatic authentication token injection and middleware support. Current stable version is 1.11.0, released as part of the Piral ecosystem with regular updates. Key differentiators: integrates with Piral's auth system, supports relative URLs to a configurable base URL, offers middleware pipeline for extending fetch behavior, and returns a slightly different response object than the browser fetch.","status":"active","version":"1.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/smapiot/piral","tags":["javascript","piral","pilet-api","smapiot","portal","modules","api","fetch","plugin","typescript"],"install":[{"cmd":"npm install piral-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add piral-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add piral-fetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency required for plugin integration","package":"piral-core","optional":false}],"imports":[{"note":"ESM-only; piral-fetch is purely ESM. No default export, named import is correct.","wrong":"const createFetchApi = require('piral-fetch')","symbol":"createFetchApi","correct":"import { createFetchApi } from 'piral-fetch'"},{"note":"Default import incorrect; must use named import.","wrong":"import createFetchApi from 'piral-fetch'","symbol":"createFetchApi","correct":"import { createFetchApi } from 'piral-fetch'"},{"note":"In Node.js with CommonJS, use dynamic import instead of require().","wrong":"const { createFetchApi } = require('piral-fetch')","symbol":"createFetchApi","correct":"const { createFetchApi } = await import('piral-fetch')"}],"quickstart":{"code":"import { createInstance } from 'piral-core';\nimport { createFetchApi } from 'piral-fetch';\n\nconst instance = createInstance({\n  plugins: [createFetchApi({\n    base: process.env.BASE_URL ?? 'https://api.example.com',\n    default: {\n      headers: {\n        'Content-Type': 'application/json',\n      },\n    },\n  })],\n  // other config\n});\n\n// In a pilet:\nexport function setup(piral: PiletApi) {\n  piral.fetch('/items')\n    .then(res => res.body)\n    .then(data => console.log(data));\n}","lang":"typescript","description":"Sets up piral-fetch plugin with a base URL and default headers, then uses the fetch API in a pilet."},"warnings":[{"fix":"Use res.code for status code, res.body for parsed JSON (automatically parsed). Do not use res.json().","message":"Response from piral-fetch's fetch is different from browser fetch: it returns { code, body } instead of Response object.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always configure a base URL in createFetchApi options, or use absolute URLs.","message":"Relative URLs are resolved against the configured base URL. If base is not set, relative URLs may fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure fetch calls target the configured base URL, or manually add auth headers for other URLs.","message":"Authentication tokens are only automatically inserted for requests to the base URL. Requests to other origins won't get tokens.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Check the response shape: use .code (number) and .body (parsed JSON).","message":"In piral-fetch v1, fetch returns a Promise<FetchResponse<T>> with code and body. In older piral versions (pre-1.0), the return type may have been different.","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.11.0':27 'api':11,76,80 'auth':44 'authent':17 'automat':16 'base':52 'behavior':60 'browser':70 'configur':51 'current':23 'differ':65 'differenti':39 'ecosystem':34 'extend':58 'fetch':2,10,59,71,81 'inject':19 'integr':40 'javascript':72 'key':38 'microfrontend':14 'middlewar':21,55 'modul':79 'object':67 'offer':54 'part':30 'pilet':13,75 'pilet-api':74 'pipelin':56 'piral':1,5,33,42,73 'plugin':3,82 'portal':78 'provid':7 'regular':36 'relat':47 'releas':28 'respons':66 'return':62 'slight':64 'smapiot':77 'stabl':24 'standard':9 'support':22,46 'system':45 'token':18 'typescript':83 'updat':37 'url':48,53 'version':25","created_at":"2026-06-07T16:59:09.207960+00:00","updated_at":"2026-06-07T16:59:09.207960+00:00","problems":[{"fix":"Run 'npm install piral-fetch' and ensure the import is from 'piral-fetch' (not 'piral-fetch-plugin' or similar).","cause":"Missing dependency or incorrect import path.","error":"Cannot find module 'piral-fetch'"},{"fix":"Change 'import createFetchApi from \"piral-fetch\"' to 'import { createFetchApi } from \"piral-fetch\"'.","cause":"Using default import instead of named import.","error":"TypeError: (0 , piral_fetch.createFetchApi) is not a function"},{"fix":"piral-fetch returns { code, body } where body is already parsed. Use res.body directly instead of res.json().","cause":"Using browser fetch response method on piral-fetch response.","error":"Uncaught TypeError: res.json is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://piral.io","github":"https://github.com/smapiot/piral","docs":null,"changelog":null,"pypi":null,"npm":"piral-fetch","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}