fuse

library0.1.3jsnpmunverified

Fuse is a GraphQL framework designed to provide end-to-end type safety for frontend teams working with GraphQL APIs at scale. It offers a streamlined development experience by handling schema generation, client-side querying, and server-side execution. Currently, the stable version is 0.12.1, with frequent patch and minor releases addressing bug fixes, performance improvements, and feature enhancements. Key differentiators include its tight integration with tools like `gql.tada` for codegen, a focus on typesafety from schema to UI, and specific plugins for frameworks like Next.js that automate server setup. It aims to simplify the complexities of GraphQL development by abstracting away much of the boilerplate, allowing developers to focus on data modeling and application logic.

web-framework http-networking

npm install fuse

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FUSE

fuse

web-frameworkjavascriptv0.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

graphql

✓ import { graphql } from '@/fuse'

✗ import { gql } from 'fuse'

The `graphql` template tag is typically imported from '@/fuse' which acts as an alias to the generated client for defining queries and mutations, leveraging `gql.tada` internally. Do not directly import `gql` from the `fuse` package.

execute

✓ import { execute } from '@/fuse/server'

✗ import { execute } from 'fuse'

The `execute` function for server-side GraphQL operations is imported specifically from the generated server module path, typically '@/fuse/server'. Direct imports from the root `fuse` package are incorrect for execution.

Generated Types

✓ import type { TypedDocumentNode } from '@graphql-typed-document-node/core'; import type { UserQuery } from '@/fuse/types';

Fuse automatically generates TypeScript types for your schema and queries. These types are crucial for end-to-end type safety and are typically located in the generated '@/fuse/types' path or inferred via `TypedDocumentNode`. Ensure your IDE's TypeScript server is configured to pick these up.

This quickstart demonstrates how to define a GraphQL query using `graphql` from `@/fuse` and execute it server-side using `execute` from `@/fuse/server`, rendering the result.

import { graphql } from '@/fuse'; import { execute } from '@/fuse/server'; const UserQuery = graphql(` query User($id: ID!) { user(id: $id) { id name email } } `); interface UserPageProps { userId: string; } // This function might be an async component or a data loader export default async function Page({ userId }: UserPageProps) { // In a real application, userId would come from props, path params, or auth context const idToQuery = userId || 'some-default-user-id'; const result = await execute({ query: UserQuery, variables: { id: idToQuery }, // Add context if your resolvers require it (e.g., auth tokens) // context: { authToken: process.env.AUTH_TOKEN ?? '' } }); if (result.errors) { console.error('GraphQL Errors:', result.errors); return <p>Error loading user data.</p>; } return ( <div> <h1>User Profile</h1> {result.data?.user ? ( <p>Welcome, {result.data.user.name} ({result.data.user.email})!</p> ) : ( <p>User not found.</p> )} </div> ); }

Debug

Known issues

gotchaWhen using Fuse with Next.js, `fuse dev` should not be run manually. The `create-fuse-app` tool configures a Next.js plugin and an API route (`/api/fuse`) to manage the API server automatically within the Next.js development workflow.

fix

Ensure `next.config.js` includes the Fuse plugin. Let Next.js handle the dev server start; `fuse dev` is for non-Next.js environments.

affects: >=0.1.0

breakingThe internal export for RSC (React Server Components) was renamed from `rsc` to `__internal_execute` to prevent accidental direct imports and misuse. Relying on the `rsc` export directly will cause issues.

fix

Avoid direct imports of `__internal_execute`. Use the standard `execute` function from `@/fuse/server` for server-side operations, which should abstract this internal detail.

affects: >=0.11.2

gotchaFuse leverages `gql.tada` for its codegen process. If you have an existing or custom codegen setup, Fuse will attempt to integrate with it. If no prior codegen is detected, it defaults to using `gql.tada`.

fix

If you have an existing codegen, ensure it's compatible or adjust your setup. If starting fresh, be aware that `gql.tada` is the default. Consult the Fuse documentation for integrating with specific codegen tools.

affects: >=0.11.0

gotchaOutdated versions of the `urql` dependency (used internally by Fuse) have had security vulnerabilities. Regularly updating Fuse ensures you benefit from the latest patches, including those related to its internal dependencies.

fix

Keep your `fuse` package up-to-date by regularly running `npm update fuse` or `yarn upgrade fuse` to incorporate security fixes and other improvements.

affects: <0.11.4

Errors

Common errors & fixes

Cannot find name 'graphql' or cannot find module '@/fuse'.

The `@/fuse` alias is not correctly configured in your project's TypeScript or bundler configuration, or the Fuse client code has not been generated.

fix

Run `npx create-fuse-app` to set up the project and ensure `tsconfig.json` or equivalent bundler config has path aliases defined. Also, ensure `npx fuse dev` (or your Next.js dev server) is running to generate the client.

Property 'data' does not exist on type 'unknown'.

This typically means TypeScript isn't correctly picking up the generated types for your GraphQL query results, leading to `any` or `unknown` types.

fix

Verify that your `tsconfig.json` includes the generated types directory (e.g., `include: ['./src/**/*.ts', './src/**/*.tsx', './.fuse/types.ts']`) and that your IDE's TypeScript server is restarted. Ensure the `graphql` tag is correctly used to infer types.

Error: Schema not found or could not be loaded.

The Fuse API server (or `fuse dev` process) failed to find or generate the GraphQL schema, or it's not running.

fix

Ensure your GraphQL schema files are correctly located and valid. Run `npx fuse dev` (or start your Next.js app) to initialize the schema and codegen. Check the console for schema parsing errors.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

urqlrequiredUsed internally, security updates are tracked.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/StellateHQ/fuse ↗

packagehttps://www.npmjs.com/package/fuse ↗

homepagehttps://fuse-graphql.org ↗