{"_id":"@api-hooks/hex","name":"@api-hooks/hex","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@api-hooks/hex","version":"1.0.0","description":"React hooks for the Hex.pm REST API, built on @tanstack/react-query","keywords":["react","hooks","hex","hex.pm","elixir","erlang","registry","api","react-query","tanstack"],"license":"MIT","homepage":"https://github.com/ElJijuna/api-hooks#readme","repository":{"type":"git","url":"git+https://github.com/ElJijuna/api-hooks.git","directory":"packages/hex"},"bugs":{"url":"https://github.com/ElJijuna/api-hooks/issues"},"publishConfig":{"access":"public"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./types":{"types":"./dist/types.d.ts","import":"./dist/types.js"}},"sideEffects":false,"scripts":{"build":"vite build && tsc --emitDeclarationOnly --declarationMap","dev":"vite build --watch","test":"jest --passWithNoTests","test:coverage":"jest --coverage --passWithNoTests","typecheck":"tsc --noEmit","docs":"typedoc"},"peerDependencies":{"@tanstack/react-query":"^5.0.0","react":">=19.0.0"},"dependencies":{"hex-api-client":"^1.0.0"},"devDependencies":{"@tanstack/react-query":"^5.101.0","@testing-library/react":"^16.3.2","jest":"^30.4.2","jest-environment-jsdom":"^30.4.1","react":"^19.2.7","react-dom":"^19.2.7","typedoc":"^0.28.19","vite":"^8.0.16","vite-magic-tree-shaking":"^1.0.0"},"author":{"name":"pilmee","email":"pilmee@gmail.com","url":"https://github.com/ElJijuna"},"gitHead":"68afa61cd684f3fa67457294be08f568aeae1b7c","_id":"@api-hooks/hex@1.0.0","_nodeVersion":"22.23.1","_npmVersion":"11.18.0","dist":{"integrity":"sha512-aV36wlDfXVWKbUw0xvDLXnX2SKOQTd4FnFdy0RmoPFJ6vj4Bt3vR9RAOm3szueHA1qcUupgai0NcyKM75UHIlA==","shasum":"937c7877b4f91c62f27f8b5f970091717c1b41ff","tarball":"https://registry.npmjs.org/@api-hooks/hex/-/hex-1.0.0.tgz","fileCount":43,"unpackedSize":40386,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGsfeNNSMnEwVyzM/sTIN4q6RYhWxmG8o0HNCIybTuljAiBwq6w+4EJmlSfkLbq5RdNyM+fJFaFHVjL+GfKHChOpRA=="}]},"_npmUser":{"name":"pilmee","email":"pilmee@gmail.com"},"directories":{},"maintainers":[{"name":"pilmee","email":"pilmee@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hex_1.0.0_1783080732334_0.07688021972064063"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-03T12:12:12.152Z","1.0.0":"2026-07-03T12:12:12.483Z","modified":"2026-07-03T12:12:12.730Z"},"maintainers":[{"name":"pilmee","email":"pilmee@gmail.com"}],"description":"React hooks for the Hex.pm REST API, built on @tanstack/react-query","homepage":"https://github.com/ElJijuna/api-hooks#readme","keywords":["react","hooks","hex","hex.pm","elixir","erlang","registry","api","react-query","tanstack"],"repository":{"type":"git","url":"git+https://github.com/ElJijuna/api-hooks.git","directory":"packages/hex"},"author":{"name":"pilmee","email":"pilmee@gmail.com","url":"https://github.com/ElJijuna"},"bugs":{"url":"https://github.com/ElJijuna/api-hooks/issues"},"license":"MIT","readme":"# @api-hooks/hex\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/ElJijuna/api-hooks/main/public/assets/api-hooks.png\" alt=\"api-hooks logo\" width=\"240\" />\n</p>\n\nReact hooks for the [Hex.pm REST API](https://hex.pm/api), built on [`hex-api-client`](https://www.npmjs.com/package/hex-api-client) and [`@tanstack/react-query`](https://tanstack.com/query).\n\n[![npm](https://img.shields.io/npm/v/@api-hooks/hex)](https://www.npmjs.com/package/@api-hooks/hex)\n[![npm downloads](https://img.shields.io/npm/dm/@api-hooks/hex)](https://www.npmjs.com/package/@api-hooks/hex)\n[![CI](https://github.com/ElJijuna/api-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/ElJijuna/api-hooks/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n\n## Requirements\n\n| Peer dependency | Version |\n| --------------- | ------- |\n| `react` | `>=19.0.0` |\n| `@tanstack/react-query` | `^5.0.0` |\n\n## Installation\n\n```bash\nnpm install @api-hooks/hex @tanstack/react-query\n```\n\n## Setup\n\nWrap your application with a `QueryClientProvider` and a `HexClientProvider` once at the root:\n\n```tsx\nimport { QueryClient, QueryClientProvider } from '@tanstack/react-query';\nimport { HexClientProvider } from '@api-hooks/hex';\n\nconst queryClient = new QueryClient();\n\nexport default function App() {\n  return (\n    <QueryClientProvider client={queryClient}>\n      <HexClientProvider>\n        <YourApp />\n      </HexClientProvider>\n    </QueryClientProvider>\n  );\n}\n```\n\nBy default, requests go to `hex.pm/api`. To point at a self-hosted Hex.pm instance, pass `baseUrl` through `HexClientProvider`:\n\n```tsx\n<HexClientProvider options={{ baseUrl: 'https://my-hex.example.com/api' }}>\n  <YourApp />\n</HexClientProvider>\n```\n\n`HexClientProvider` is optional — hooks fall back to a default `HexClient` (pointed at `hex.pm/api`) when no provider is present.\n\n## Hooks\n\nQuery hooks return a [`UseQueryResult`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) — you get the full TanStack Query API: `data`, `isLoading`, `isFetching`, `isError`, `error`, `refetch`, and more. `useHexPackagesInfinite` returns a [`UseInfiniteQueryResult`](https://tanstack.com/query/latest/docs/framework/react/reference/useInfiniteQuery).\n\n| Hook | Description | Returns |\n| ---- | ----------- | ------- |\n| [`useHexPackage(name, options?)`](#usehexpackagename-options) | Full package metadata | `HexPackage` |\n| [`useHexPackageVersions(name, options?)`](#usehexpackageversionsname-options) | All published versions of a package | `string[]` |\n| [`useHexPackageRelease(name, version, options?)`](#usehexpackagereleasename-version-options) | Full release metadata for a version | `HexRelease` |\n| [`useHexPackageLatestStable(name, options?)`](#usehexpackagelateststablename-options) | Latest stable version string | `string \\| null` |\n| [`useHexPackages(params?, options?)`](#usehexpackagesparams-options) | List/search Hex.pm packages | `HexPackage[]` |\n| [`useHexPackagesInfinite(options?)`](#usehexpackagesinfiniteoptions) | Infinite-scroll variant of `useHexPackages` | `InfiniteData<HexPackage[]>` |\n\n---\n\n## API Reference\n\n### `useHexPackage(name, options?)`\n\nFetches full package metadata from Hex.pm.\n\n```tsx\nimport { useHexPackage } from '@api-hooks/hex';\n\nfunction PackageDetail() {\n  const { data } = useHexPackage('phoenix');\n\n  return <p>{data?.meta.description}</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useHexPackageVersions(name, options?)`\n\nFetches all published version strings of a Hex.pm package.\n\n```tsx\nimport { useHexPackageVersions } from '@api-hooks/hex';\n\nfunction VersionList() {\n  const { data } = useHexPackageVersions('phoenix');\n\n  return <ul>{data?.map(v => <li key={v}>{v}</li>)}</ul>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useHexPackageRelease(name, version, options?)`\n\nFetches full release metadata for a specific package version.\n\n```tsx\nimport { useHexPackageRelease } from '@api-hooks/hex';\n\nfunction ReleaseDetail() {\n  const { data } = useHexPackageRelease('phoenix', '1.7.10');\n\n  return <p>{data?.meta.elixir}</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` or `version` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useHexPackageLatestStable(name, options?)`\n\nFetches the `latest_stable_version` string for a Hex.pm package.\n\n```tsx\nimport { useHexPackageLatestStable } from '@api-hooks/hex';\n\nfunction LatestVersion() {\n  const { data } = useHexPackageLatestStable('phoenix');\n\n  return <p>Latest: {data}</p>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query (also disabled when `name` is empty) |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useHexPackages(params?, options?)`\n\nLists or searches Hex.pm packages.\n\n```tsx\nimport { useHexPackages } from '@api-hooks/hex';\n\nfunction PackageSearch() {\n  const { data, isLoading } = useHexPackages({ search: 'phoenix', per_page: 10 });\n\n  if (isLoading) return <p>Loading…</p>;\n\n  return <ul>{data?.map(p => <li key={p.name}>{p.name}</li>)}</ul>;\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `enabled` | `boolean` | `true` | Disable the query |\n| `queryOptions` | `QueryOverrides<TData>` | `undefined` | Override TanStack Query options (`staleTime`, `retry`, `gcTime`, `select`, etc.) |\n\n---\n\n### `useHexPackagesInfinite(options?)`\n\nInfinite-scroll variant of `useHexPackages`. Each page advances the 1-based `page` number. Hex.pm's list endpoint returns no total count, so `hasNextPage` is derived heuristically: a full page (`length === per_page`) implies more results may exist. Call `fetchNextPage()` to load the next batch — results accumulate in `data.pages`.\n\n```tsx\nimport { useHexPackagesInfinite } from '@api-hooks/hex';\n\nfunction PackageSearchInfinite() {\n  const { data, fetchNextPage, hasNextPage } = useHexPackagesInfinite({ search: 'ecto' });\n\n  return (\n    <>\n      {data?.pages.flat().map(p => <div key={p.name}>{p.name}</div>)}\n      {hasNextPage && <button onClick={() => fetchNextPage()}>Load more</button>}\n    </>\n  );\n}\n```\n\n| Option | Type | Default | Description |\n| ------ | ---- | ------- | ----------- |\n| `search` | `string` | `undefined` | Search text |\n| `per_page` | `number` | `10` | Page size |\n| `enabled` | `boolean` | `true` | Disable the query |\n| `queryOptions` | `InfiniteQueryOverrides<TData>` | `undefined` | Override TanStack Query options |\n\n---\n\n## License\n\nMIT © [ElJijuna](https://github.com/ElJijuna)\n","readmeFilename":"README.md","_rev":"1-59ce9cda0aec7ac027cbdc222a8d4fbe"}