{"id":13208,"library":"fuse","title":"Fuse: End-to-End Type-Safe GraphQL Framework","description":"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.","status":"active","version":"0.12.1","language":"javascript","source_language":"en","source_url":"https://github.com/StellateHQ/fuse","tags":["javascript","typescript"],"install":[{"cmd":"npm install fuse","lang":"bash","label":"npm"},{"cmd":"yarn add fuse","lang":"bash","label":"yarn"},{"cmd":"pnpm add fuse","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally, security updates are tracked.","package":"urql","optional":false}],"imports":[{"note":"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.","wrong":"import { gql } from 'fuse'","symbol":"graphql","correct":"import { graphql } from '@/fuse'"},{"note":"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.","wrong":"import { execute } from 'fuse'","symbol":"execute","correct":"import { execute } from '@/fuse/server'"},{"note":"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.","symbol":"Generated Types","correct":"import type { TypedDocumentNode } from '@graphql-typed-document-node/core';\nimport type { UserQuery } from '@/fuse/types';"}],"quickstart":{"code":"import { graphql } from '@/fuse';\nimport { execute } from '@/fuse/server';\n\nconst UserQuery = graphql(`\n  query User($id: ID!) {\n    user(id: $id) {\n      id\n      name\n      email\n    }\n  }\n`);\n\ninterface UserPageProps {\n  userId: string;\n}\n\n// This function might be an async component or a data loader\nexport default async function Page({ userId }: UserPageProps) {\n  // In a real application, userId would come from props, path params, or auth context\n  const idToQuery = userId || 'some-default-user-id'; \n  \n  const result = await execute({\n    query: UserQuery,\n    variables: { id: idToQuery },\n    // Add context if your resolvers require it (e.g., auth tokens)\n    // context: { authToken: process.env.AUTH_TOKEN ?? '' }\n  });\n\n  if (result.errors) {\n    console.error('GraphQL Errors:', result.errors);\n    return <p>Error loading user data.</p>;\n  }\n\n  return (\n    <div>\n      <h1>User Profile</h1>\n      {result.data?.user ? (\n        <p>Welcome, {result.data.user.name} ({result.data.user.email})!</p>\n      ) : (\n        <p>User not found.</p>\n      )}\n    </div>\n  );\n}","lang":"typescript","description":"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."},"warnings":[{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.11.2"},{"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.","message":"Fuse 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`.","severity":"gotcha","affected_versions":">=0.11.0"},{"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.","message":"Outdated 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.","severity":"gotcha","affected_versions":"<0.11.4"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `@/fuse` alias is not correctly configured in your project's TypeScript or bundler configuration, or the Fuse client code has not been generated.","error":"Cannot find name 'graphql' or cannot find module '@/fuse'."},{"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.","cause":"This typically means TypeScript isn't correctly picking up the generated types for your GraphQL query results, leading to `any` or `unknown` types.","error":"Property 'data' does not exist on type 'unknown'."},{"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.","cause":"The Fuse API server (or `fuse dev` process) failed to find or generate the GraphQL schema, or it's not running.","error":"Error: Schema not found or could not be loaded."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}