DOCSEARCHbyAlgolia
Submit Docs

nitrogql

repository·master·Indexed 43 days ago

https://github.com/uhyo/nitrogql

A toolchain for TypeScript projects providing type generation for GraphQL schemas and queries with sourcemap support and static checking to prevent runtime type mismatches. It supports schema-first workflows and integrates with Next.js, Vite, webpack, Rollup, and Jest via dedicated loaders and plugins.

Tokens
53.9K
Snippets
211
Records
251
Agent score
56%

What's inside nitrogql

  1. Overview of nitrogql

    master

    nitrogql is a toolchain designed for using GraphQL in TypeScript projects. It provides two primary capabilities:

    1. Type generation with sourcemap support: It generates TypeScript types for your GraphQL schema and queries. It also produces sourcemap files that map these generated types back to the original GraphQL source. This allows IDEs (like VSCode) to jump directly to the original GraphQL query/schema instead of showing generated code when using commands like "Peek Definition".
    2. Static checking: It can statically check your GraphQL code to prevent runtime errors caused by type mismatches between your queries and your schema.

  2. Use @nitrogql/wasi-preview1 for WASI preview1 support

    master

    The @nitrogql/wasi-preview1 package provides an implementation of the WASI (WebAssembly System Interface) preview1 specification.

    Important Limitation: This package only supports a subset of the WASI preview1 specification. Ensure your WebAssembly module's requirements are compatible with the supported subset before integration.

  3. How nitrogql works in a schema-first Next.js application

    master

    Nitrogql enables a schema-first development workflow where the GraphQL schema (located in src/schema/*.graphql) acts as the single source of truth for both client and server code.

    Client-side Workflow

    Client-side code (e.g., in src/app/TodoList) uses GraphQL files. When you run npm run generate, nitrogql:

    1. Generates TypeScript types for the GraphQL operations.
    2. Creates files with a .d.graphql.ts suffix next to the original files.
    3. Uses the @nitrogql/graphql-loader webpack loader to transform .graphql files into exported GraphQL document nodes. These nodes can be used directly with clients like Apollo Client.

    Server-side Workflow

    Server-side code (e.g., in src/app/graphql/route.ts) implements the schema using the generated Resolvers type. This type ensures that TypeScript validates whether all required resolvers defined in the schema are correctly implemented.

  4. Run the nitrogql + Next.js example project

    master

    To run the provided Next.js example project, follow these steps in order:

    1. Install dependencies (without workspace resolution).
    2. Run the nitrogql generation command to create types and GraphQL document nodes.
    3. Start the Next.js development server.

    Note: The npm run generate step is critical as it populates the .d.graphql.ts files required for type safety and client-side GraphQL usage.

    npm install --workspaces=false
npm run generate
npm run dev

  6. Use @nitrogql/esbuild-register with Node.js

    master

    The @nitrogql/esbuild-register package allows you to use esbuild to register and transform files during Node.js execution. The command used to load the package depends on your Node.js version.

    For Node.js >= 20.6.0 or >= 18.19.0

    Use the --import flag:

    node --import=@nitrogql/esbuild-register

    For Node.js < 20.6.0 and < 18.19.0

    Use both --import and the --experimental-loader flag pointing to the hook:

    node --import=@nitrogql/esbuild-register --experimental-loader=@nitrogql/esbuild-register/hook
    # For Node.js >= 20.6.0 or >= 18.19.0
node --import=@nitrogql/esbuild-register

# For Node.js < 20.6.0 and < 18.19.0
node --import=@nitrogql/esbuild-register --experimental-loader=@nitrogql/esbuild-register/hook

  7. Use nitrogql in a Vite application

    master

    To use nitrogql in a Vite project, you need to provide a GraphQL schema (as an introspection JSON file) and your GraphQL operations (as .graphql files).

    1. Provide a Schema: Place your introspection JSON in a known location (e.g., src/schema/pokeapi.json). In production, use a tool to fetch this from your API.
    2. Write Operations: Create .graphql files containing your queries or mutations (e.g., src/pokemonList.graphql).
    3. Generate Types: Run the generation command to create TypeScript definitions. These are generated with a .d.graphql.ts suffix next to your original .graphql file.
    4. Integration: Use @nitrogql/rollup-plugin (or the equivalent Vite/Rollup integration) to allow importing .graphql files directly into your client-side code. The plugin converts the .graphql file into a GraphQL document node that can be used with clients like Apollo Client.

    Setup and Execution

    npm install --workspaces=false
npm run generate
npm run dev

  8. Configure @nitrogql/jest-transform in Jest

    master

    Use @nitrogql/jest-transform as a custom Jest transformer to convert .graphql files into JavaScript modules that export the parsed GraphQL document. You must provide a configFile path in the transformer options pointing to your nitrogql.config.js or nitrogql.config.yml.

    {
  "transform": {
    "^.+\.graphql$": ["@nitrogql/jest-transform", {
      "configFile":  path.resolve(__dirname, "nitrogql.config.js")
    }]
  }
}

  10. Enable CommonJS support with @nitrogql/jest-transform

    master

    By default, @nitrogql/jest-transform only emits ES modules. If your test environment requires CommonJS, you must chain another transformer (like babel-jest or ts-jest) using the additionalTransformer option.

    Because secondary transformers often expect specific file extensions, you must also use the additionalTransformerFilenameSuffix option to rename the output of the first transform so the second one can process it correctly.

    {
  "transform": {
    // For example, if you are using ts-jest...
    "^.+\.tsx?": ["ts-jest", { isolatedModules: true }],
    "^.+\.graphql$": ["@nitrogql/jest-transform", {
      "configFile":  path.resolve(__dirname, "nitrogql.config.yml"),
      // Then, use the additionalTransformer option to apply ts-jest to the output.
      "additionalTransformer": ["ts-jest", { isolatedModules: true }],
      // ts-jest expects .ts files, so we need to change the file extension
      // by applying the additionalTransformerFilenameSuffix option.
      "additionalTransformerFilenameSuffix": ".ts"
    }]
  },
}

  11. Install nitrogql loaders for bundlers

    master

    To integrate GraphQL into your front-end project's build process, you must install the appropriate loader for your bundler:

    For webpack-based projects:

    npm install --save-dev @nitrogql/graphql-loader

    For Rollup-based projects:

    npm install --save-dev @nitrogql/rollup-plugin
    # webpack
npm install --save-dev @nitrogql/graphql-loader

# Rollup
npm install --save-dev @nitrogql/rollup-plugin

  12. How nitrogql resolves schemas

    master

    Nitrogql supports three primary ways to load a GraphQL schema:

    1. GraphQL Files: Standard .graphql files containing type system or extension documents.
    2. Introspection JSON: A JSON file produced by a GraphQL introspection query. Note that if an introspection JSON is used, you cannot mix it with other GraphQL documents in the same run.
    3. Schema JavaScript: A .js file that exports schema definitions. This allows for dynamic schema construction and is often used in conjunction with plugins.

    When multiple GraphQL documents are provided, nitrogql merges them into a single unified schema. If plugins are configured, they can also contribute schema extensions during the loading process.