Historical source and current status
This is the complete add-action-and-hook guide from ton-org/kit, recorded at 2026-04-06 UTC. Verified Git history records its deletion at 2026-05-28 UTC. The file was unchanged between the historical source commit and the parent of that deletion. The current repository snapshot checked on 2026-10-18 UTC no longer contains this path.
This is a historical original, not a claim that the old skill remains installable or that its examples match current AppKit. The directory name, ID, repository and installation command are preserved. The following source instructions and examples were not executed, tested or used to run project quality checks or documentation generation here.
Source: historical guide; deletion commit. Observed 2026-10-18 UTC.
Complete historical published guide
name: add-action-and-hook description: How to add a new action and hook to AppKit. Use when creating new getXxx/watchXxx actions and useXxx hooks.
Adding a New Action and Hook to AppKit
This skill describes the end-to-end process of adding a new action (getXxx / watchXxx) and a corresponding React hook (useXxx) to the AppKit library. Follow each step in order, consulting existing examples as reference.
Step 1: Create the Action in appkit
There are two types of actions:
- Get actions — fetch data asynchronously (
getXxx). Used for one-time reads. - Watch actions — subscribe to state changes (
watchXxx). Used when the value can change over time and the UI needs to react.
1.1 Study existing actions
Before creating your own, look at similar actions in packages/appkit/src/actions/ to understand the pattern.
Get action example:
packages/appkit/src/actions/network/get-networks.ts
Watch action example:
packages/appkit/src/actions/network/watch-networks.ts
export const watchNetworks = (appKit: AppKit, parameters: WatchNetworksParameters): WatchNetworksReturnType => {
const { onChange } = parameters;
const unsubscribe = appKit.emitter.on(NETWORKS_EVENTS.UPDATED, () => {
onChange(getNetworks(appKit));
});
return unsubscribe; // caller is responsible for cleanup
};
1.2 Create the action file
Create packages/appkit/src/actions/<category>/get-xxx.ts (or watch-xxx.ts).
Get action structure:
import type { AppKit } from '../../core/app-kit';
export interface GetXxxOptions { /* ... */ }
export type GetXxxReturnType = Promise<number>;
export const getXxx = async (appKit: AppKit, options: GetXxxOptions = {}): GetXxxReturnType => {
// All business logic goes here
return result;
};
1.3 Export the action
Add exports to packages/appkit/src/actions/index.ts:
export {
getXxx,
type GetXxxOptions,
type GetXxxReturnType,
} from './<category>/get-xxx';
Step 2: Create the Query or Mutation in appkit (for get actions only)
Watch actions skip this step entirely — they go directly to the hook (Step 3).
For get actions, create a @tanstack/react-query integration in packages/appkit/src/queries/.
Query — for reading data (getXxx)
Study packages/appkit/src/queries/balances/get-balance-by-address.ts as a reference.
Create packages/appkit/src/queries/<category>/get-xxx.ts:
import type { AppKit } from '../../core/app-kit';
import { getXxx } from '../../actions/<category>/get-xxx';
import type { GetXxxOptions, GetXxxReturnType } from '../../actions/<category>/get-xxx';
import type { QueryOptions, QueryParameter } from '../../types/query';
import type { Compute, ExactPartial } from '../../types/utils';
import { filterQueryOptions } from '../../utils';
export type GetXxxErrorType = Error;
export type GetXxxData = GetXxxQueryFnData;
export type GetXxxQueryConfig<selectData = GetXxxData> = Compute<ExactPartial<GetXxxOptions>> &
QueryParameter<GetXxxQueryFnData, GetXxxErrorType, selectData, GetXxxQueryKey>;
export const getXxxQueryOptions = <selectData = GetXxxData>(
appKit: AppKit,
options: GetXxxQueryConfig<selectData> = {},
): GetXxxQueryOptions<selectData> => {
return {
...options.query,
queryFn: async (context) => {
const [, parameters] = context.queryKey as [string, GetXxxOptions];
return getXxx(appKit, parameters);
},
queryKey: getXxxQueryKey(options),
};
};
export type GetXxxQueryFnData = Compute<Awaited<GetXxxReturnType>>;
export const getXxxQueryKey = (options: Compute<ExactPartial<GetXxxOptions>> = {}): GetXxxQueryKey =>
['xxx', filterQueryOptions(options)] as const;
export type GetXxxQueryKey = readonly ['xxx', Compute<ExactPartial<GetXxxOptions>>];
export type GetXxxQueryOptions<selectData = GetXxxData> = QueryOptions<
GetXxxQueryFnData, GetXxxErrorType, selectData, GetXxxQueryKey
>;
Mutation — for write/side-effect actions (doXxx)
Study packages/appkit/src/queries/transaction/transfer-ton.ts as a reference.
Create packages/appkit/src/queries/<category>/do-xxx.ts:
import type { AppKit } from '../../core/app-kit';
import { doXxx } from '../../actions/<category>/do-xxx';
import type { DoXxxOptions, DoXxxReturnType } from '../../actions/<category>/do-xxx';
import type { MutationOptions } from '../../types/query';
import type { Compute } from '../../types/utils';
export type DoXxxErrorType = Error;
export type DoXxxData = Awaited<DoXxxReturnType>;
export type DoXxxVariables = DoXxxOptions;
export type DoXxxMutationOptions = MutationOptions<DoXxxData, DoXxxErrorType, DoXxxVariables>;
export const doXxxMutationOptions = (appKit: AppKit): DoXxxMutationOptions => ({
mutationFn: (variables) => doXxx(appKit, variables),
});
Export the query/mutation
Add to packages/appkit/src/queries/index.ts under the appropriate category comment:
// For a query:
export {
getXxxQueryOptions,
type GetXxxData,
type GetXxxErrorType,
type GetXxxQueryConfig,
} from './<category>/get-xxx';
// For a mutation:
export {
doXxxMutationOptions,
type DoXxxData,
type DoXxxErrorType,
type DoXxxMutationOptions,
type DoXxxVariables,
} from './<category>/do-xxx';
Step 3: Create the Hook in appkit-react
The hook should be a thin wrapper — all business logic lives in appkit. This design makes it easy to later build appkit-vue or other framework adapters.
Hook from a query (useXxx)
Study packages/appkit-react/src/features/nft/hooks/use-nft.ts as the canonical reference.
Create packages/appkit-react/src/features/<category>/hooks/use-xxx.ts:
import { getXxxQueryOptions } from '@ton/appkit/queries';
import type { GetXxxData, GetXxxErrorType, GetXxxQueryConfig } from '@ton/appkit/queries';
import { useAppKit } from '../../../hooks/use-app-kit';
import { useQuery } from '../../../libs/query';
import type { UseQueryReturnType } from '../../../libs/query';
export type UseXxxParameters<selectData = GetXxxData> = GetXxxQueryConfig<selectData>;
export type UseXxxReturnType<selectData = GetXxxData> = UseQueryReturnType<selectData, GetXxxErrorType>;
/**
* Hook to get ...
*/
export const useXxx = <selectData = GetXxxData>(
parameters: UseXxxParameters<selectData> = {},
): UseXxxReturnType<selectData> => {
const appKit = useAppKit();
return useQuery(getXxxQueryOptions(appKit, parameters));
};
Hook from a mutation (useDoXxx)
Study packages/appkit-react/src/features/transaction/hooks/use-transfer-ton.ts as the canonical reference.
Hook from a watch action (useXxx)
Watch-based hooks use useSyncExternalStore directly — no query/mutation involved.
Study packages/appkit-react/src/features/network/hooks/use-networks.ts as the canonical reference:
import { useSyncExternalStore, useCallback } from 'react';
import { getXxx, watchXxx } from '@ton/appkit';
import type { GetXxxReturnType } from '@ton/appkit';
import { useAppKit } from '../../../hooks/use-app-kit';
export type UseXxxReturnType = GetXxxReturnType;
export const useXxx = (): UseXxxReturnType => {
const appKit = useAppKit();
const subscribe = useCallback(
(onChange: () => void) => watchXxx(appKit, { onChange }),
[appKit],
);
const getSnapshot = useCallback(() => getXxx(appKit), [appKit]);
return useSyncExternalStore(subscribe, getSnapshot, () => initialValue);
};
Export the hook
Add to packages/appkit-react/src/features/<category>/index.ts:
export { useXxx, type UseXxxParameters, type UseXxxReturnType } from './hooks/use-xxx';
Step 4: Add Examples and Tests
4.1 Action example
Create demo/examples/src/appkit/actions/<category>/get-xxx.ts:
import type { AppKit } from '@ton/appkit';
import { getXxx } from '@ton/appkit';
export const getXxxExample = async (appKit: AppKit) => {
// SAMPLE_START: GET_XXX
const result = await getXxx(appKit);
console.log('Result:', result);
// SAMPLE_END: GET_XXX
};
Export it in demo/examples/src/appkit/actions/<category>/index.ts.
4.2 Hook example
Create demo/examples/src/appkit/hooks/<category>/use-xxx.tsx:
import { useXxx } from '@ton/appkit-react';
export const UseXxxExample = () => {
// SAMPLE_START: USE_XXX
const { data } = useXxx();
return <div>Result: {data}</div>;
// SAMPLE_END: USE_XXX
};
Export it in demo/examples/src/appkit/hooks/<category>/index.ts.
4.3 Write tests
Important: Do NOT create a new test file per example. Add tests to the existing <category>.test.ts / <category>.test.tsx file in the same directory.
Action test:
describe('getXxxExample', () => {
it('should log the result', async () => {
vi.spyOn(appKit.networkManager, 'getClient').mockReturnValue({
getSomeData: vi.fn().mockResolvedValue({ value: 42 }),
} as any);
await getXxxExample(appKit);
expect(consoleSpy).toHaveBeenCalledWith('Result:', 42);
});
});
Hook test (add describe block inside the existing describe('... Hooks Examples', ...))
If the mock appKit in beforeEach doesn't have the required mocks (e.g., getClient), add them to the shared setup.
Step 5: Update Templates and Docs
5.1 Update action template
Edit template/appkit-actions.md, add after the nearest related action:
### `getXxx`
Description of what the action does.
%%demo/examples/src/appkit/actions/<category>#GET_XXX%%
5.2 Update hooks template
Edit template/appkit-hooks.md, add after the nearest related hook:
### `useXxx`
Hook to ...
%%demo/examples/src/appkit/hooks/<category>#USE_XXX%%
5.3 Run quality check
pnpm quality
All tests and type checks must pass before continuing.
5.4 Regenerate documentation
pnpm docs:update
Verify the relevant .md files in packages/appkit/docs/ and packages/appkit-react/docs/ were updated.
MIT license and attribution
Original guide: TonTech. The complete source text above is unchanged.
MIT License
Copyright (c) 2025 TonTech
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.