hook-use-api

React hooks for authenticated API calls with shared config, fetch, and swr.

GitHub: ju-bezdek/hook-use-api

Install

Package

npm install hook-use-api swr

Codex skill

npx --package hook-use-api add-skill

This creates or updates .agents/skills/use-api in the current project.

What it provides

Use hook-use-api when you want one consistent way to:

• fetch data for rendering with useApiFetch
• call mutating endpoints with useApiEndpoint
• centralize auth headers, base URL, and unauthorized handling
• avoid calling fetch or axios directly throughout the app

Initialize shared API config

'use client';

import { setGlobalApiConfig, setGlobalToastFunction } from 'hook-use-api';

setGlobalApiConfig({
  baseUrl: 'https://api.example.com',
  authorize: async () => ({
    Authorization: `Bearer ${localStorage.getItem('token') ?? ''}`,
  }),
  onUnauthorized: async () => {
    window.location.href = '/login';
  },
});

setGlobalToastFunction(({ title, description, status }) => {
  console.log(title, description, status);
});

Fetch data with useApiFetch

Use useApiFetch for loading data that should be rendered on the page.

import { useApiFetch } from 'hook-use-api';

type Project = {
  id: string;
  name: string;
};

export function ProjectList() {
  const { data, isLoading, error, mutate } = useApiFetch<Project[]>('/api/projects');

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Failed to load projects.</div>;

  return (
    <div>
      <button onClick={() => mutate()}>Refresh</button>
      <ul>
        {data?.map((project) => (
          <li key={project.id}>{project.name}</li>
        ))}
      </ul>
    </div>
  );
}

Available options:

{
  method?: 'GET' | 'POST' | 'PATCH' | 'DELETE';
  queryArgs?: Record<string, any>;
  body?: any;
  redirectOnUnauthorized?: boolean;
  static?: boolean;
  swrOptions?: {
    refreshInterval?: number;
    revalidateIfStale?: boolean;
    revalidateOnFocus?: boolean;
    revalidateOnReconnect?: boolean;
    revalidateOnMount?: boolean;
    [key: string]: any;
  };
  onError?: (error: any) => any;
  shouldFetch?: boolean;
}

Call actions with useApiEndpoint

Use useApiEndpoint for actions that create, update, or delete data.

import { useApiEndpoint } from 'hook-use-api';

export function UpdateProfileButton({ profileId }: { profileId: string }) {
  const updateProfile = useApiEndpoint('PATCH', '/profiles/{profileId}');

  const handleClick = async () => {
    await updateProfile.invoke({
      pathArgs: { profileId },
      body: { name: 'New name' },
    });
  };

  return (
    <div>
      <button onClick={handleClick} disabled={updateProfile.isLoading}>
        {updateProfile.isLoading ? 'Saving...' : 'Update profile'}
      </button>
      {updateProfile.error && <div>{updateProfile.error.message}</div>}
    </div>
  );
}

Publish to npm

Requirements:

• an npm account with permission to publish
• package name hook-use-api available on npm
• logged in locally with npm login
• clean build output from npm run build

Recommended commands:

npm install
npm run build
npm pack
npm publish --access public

Useful verification commands:

npm whoami
npm pack --dry-run

If this is the first publish from your machine:

npm login

If you want a single publish command after reviewing the tarball:

npm publish --access public

Development

npm install
npm run build

Notes

• The package is client-side only and exports 'use client' at the entrypoint.
• react and swr are peer dependencies and should be installed by the consuming app.
• onUnauthorized is provided via shared config instead of importing app-specific auth logic into the package.