Houdini GraphQL Framework

Houdini is a GraphQL framework designed to provide a high-quality developer experience by shifting traditional runtime logic into a compile step. This approach results in an incredibly lean GraphQL abstraction for applications, minimizing bundle size while providing powerful features.

Key Features:

• Composable and Colocated Data Requirements: Define data needs directly alongside your components.
• Normalized Cache: Includes declarative updates for managing application state.
• Generated Types: Automatic type generation for your GraphQL schema and queries.
• Subscriptions: Support for real-time data updates.
• Pagination: Supports both cursor-based and offset-based pagination.

The Houdini documentation site is organized into framework-specific directories and shared content sections:

• svelte/: Contains documentation for houdini-svelte.
• react/: Contains documentation for houdini-react.
• shared/: Contains sidebar sections that are automatically appended to the bottom of every framework's sidebar. These sections are injected using numeric prefixes starting at 100-, 101-, etc., to ensure they follow framework-specific content.
• _partials/: Contains MDX partials used for component reuse within doc pages.

The Cache API provides programmatic access to Houdini's runtime cache. It is intended as an advanced escape hatch for situations where automatic cache updates or list operation fragments are insufficient. Use it to manually read, write, subscribe to, or manage data outside of standard document stores.

Warning: If your business logic relies heavily on this API, consider opening an issue or discussion on GitHub to improve Houdini's core capabilities.

The onSignIn function in your server configuration is responsible for transforming a verified provider user into your application's session object.

Best Practices:

• Use user.sub for identity: Always use user.sub (the provider's stable, unique ID) to look up or create accounts. Do not rely on user.email, as it may be undefined if the provider has not marked the email as verified.
• Keep sessions opaque: The object returned by onSignIn is what gets stored in the session cookie. It should contain only an opaque reference (like a userId) and never the provider's raw tokens.
• Store tokens securely: If you need to call the provider's API later, store the tokens in your own database, not in the session cookie.

onSignIn: async ({ user, tokens }) => {
    // save the user to the database, etc.
    return { userId: user.sub } 
},

Fragment masking ensures components only access fields they explicitly declared, preventing them from accidentally using fields pulled in by sibling fragments.

By default, masking is enabled. You can:

1. Disable globally: Set defaultFragmentMasking: "disable" in your Houdini configuration.
2. Disable per-fragment: Use the @mask_disable directive on a specific fragment to make its fields accessible directly on the parent object.

query CurrentUser {
  me {
    uuid
    ...UserProfile @mask_disable
    ...UserMeta
  }
}
# With @mask_disable, UserProfile fields are accessible on 'me' alongside 'uuid'.

The @loading directive allows you to define a predictable data shape for fields while a query is in flight. Instead of receiving null or undefined, fields marked with @loading are replaced with pending placeholders.

Houdini processes queries top-down. Intermediate nodes retain their original type (objects remain objects, lists remain lists), and the deepest field tagged with @loading becomes the actual pending value. This allows you to safely iterate over lists or access object properties even before the data has arrived.

query ShowList {
  shows @loading {
    title
  }
}

Fragments can be nested, allowing you to build complex data requirements by composing smaller, reusable fragments. This enables a highly decoupled architecture where components can rely on other components' data requirements.

Example of nesting: If ComponentA uses fragmentA and ComponentB uses fragmentB, ComponentB can include ...fragmentA inside its own fragmentB definition. When the parent query includes ...fragmentB, it automatically satisfies the requirements for both components.

fragment SpeciesPreview on Species {
    id
    pokedexNumber
    name

    # Nesting an existing fragment
    ...SpriteInfo
}