> For the complete documentation index, see [llms.txt](https://developers.raycast.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.raycast.com/utilities/getting-started.md). # Getting Started In addition to the [Raycast API](/api-reference/cache.md) which is bundled as part of the app, we also provide a sibling package that contains a set of utilities to streamline common patterns and operations used in extensions. ![](/files/sdc8awiSTexuSlaWjU6K) ## Installation This package can be installed independently using `npm`. ``` npm install --save @raycast/utils ``` `@raycast/utils` has a [peer dependency](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependencies) on `@raycast/api`. This means that a certain version of `utils` will require a version above a certain version of `api`. `npm` will warn you if that is not the case. ## Changelog ### v2.3.0 * Added `cacheWriteDebounce` to `useCachedState`, `useCachedPromise`, `useFetch`, `useExec`, and `useStreamJSON` * Fixed paginated `useFetch` URL factories running during render, repeatedly revalidating when passed inline, and bypassing the hook's error handling when they throw * Fixed `usePromise` handling of synchronous errors, asynchronous callbacks, and automatic optimistic-update rollbacks * Fixed `useCachedPromise` returning data and pagination state belonging to a previous cache key when `keepPreviousData` is disabled * Fixed `useExec` commands waiting forever for stdin, and restored support for disabling its timeout with `timeout: 0` * Fixed OAuth token refresh recovery and custom Google and Slack refresh-token URLs * Fixed `runAppleScript` and `runPowerShellScript` ignoring `parseOutput` and always returning a string * Fixed `useSQL` throwing during render when a database is missing and retaining a stale permission view after subsequent results * Fixed stale `useAI` streams overwriting newer results and model changes not triggering a new request * Fixed `useStreamJSON` not flattening arrays returned by `transform` before filtering and paginating them * Fixed failed `useStreamJSON` downloads replacing valid caches with partial files * Fixed SQLite connections leaking when queries fail or are aborted * Fixed frecency decay calculations, in-place sorting of caller-owned arrays * Fixed `useForm.reset` ignoring explicit falsy values * Fixed `getProgressIcon` ignoring `backgroundOpacity: 0` * Fixed `runAppleScript` timeout error messages reporting `undefined` instead of the effective timeout ### v2.2.6 * Fixed an issue where refreshing OAuth tokens would fails for providers that return scope as an array instead of a string ### v2.2.5 * Fixed an issue where `useSql` would not properly show the permission priming screen ### v2.2.4 * Fixed an issue where an avatar's initials wouldn't be centered ### v2.2.3 * Fixed an issue with `useSQL` on Windows where the query would refuse to be executed because the database is locked ### v2.2.2 * Fix `useCachedState` to preserve Date objects more precisely. ### v2.2.1 * Fix compiled file to actually make `useSQL` and `executeSQL` work on Windows. ### v2.2.0 * Make `useSQL` and `executeSQL` work on Windows. ### v2.1.1 * Fix the default size of `getFavicon`. ### v2.1.0 * `getFavicon` will now respect the user's setting for the favicon provider. Note that the `Apple` provider isn't supported since it relies on a native API. ### v2.0.1 * Fix types for ESM extensions ### v2.0.0 * The library can now be tree-shaken, reducing its size considerably. * When using `usePromise` and mutating the data with an optimistic update before it is fetched, the current fetch will be aborted to avoid a race condition. * Add a new [`runPowerShellScript`](/utilities/functions/runpowershellscript.md) function. ### v1.19.1 * Fixed an issue where arguments weren't passed to `withCache`. ### v1.19.0 * Add a new [`withCache`](/utilities/functions/withcache.md) function. ### v1.18.1 * Fixed an issue where setting `timeout` to `0` in `runAppleScript` would not work. ### v1.18.0 * Add a new [\`executeSQL](/utilities/functions/executesql.md) function. ### v1.17.0 * Add a new [`createDeeplink`](/utilities/functions/createdeeplink.md) function. ### v1.16.5 * Fixed the bug where `failureToastOptions` did not apply for `useExec` and `useStreamJSON` hooks. ### v1.16.4 * Avoid throwing an error when `useFetch` can't parse the `Content-Type` header of the response. ### v1.16.3 * Fix an issue where `URLSearchParams` couldn't be passed as an option to `useFetch` or `useCachedPromise`, causing extensions to crash. ### v1.16.2 * Fixed the refresh token flow to log out the user instead of throwing an error. ### v1.16.1 * Fixed an issue where `bodyEncoding` wasn't properly used in OAuthService. ### v1.16.0 * Add a `failureToastOptions` prop to `useFetch`, `useCachedPromise`, and `usePromise` to make it possible to customize the error displayed instead of a generic "Failed to fetch latest data". ### v1.15.0 * Add [`useLocalStorage`](/utilities/react-hooks/uselocalstorage.md) hook. ### v1.14.0 * Add [`useStreamJSON`](/utilities/react-hooks/usestreamjson.md) hook. ### v1.13.6 * Updated `useFetch`'s `mapResult` type to allow returning `cursor` in addition to `data` and `hasMore`. ### v1.13.5 * Extended `PaginationOptions` with `cursor`. ### v1.13.4 * Fixed non-paginated version of `useFetch` not being re-run when `url` changes. ### v1.13.3 * Fixed `optimisticUpdate` not working when paginating beyond the first page when using `useCachedPromise` or other hooks that build on top of it.. * Fixed `useFetch` type requiring `mapResult` for non-paginated overload. ### v1.13.2 * Added default OAuth URLs for Google, Jira, and Zoom ### v1.13.1 * Fixed `useFetch` type for non-paginated overload. ### v1.13.0 * Added pagination support to `usePromise`, `useCachedPromise` and `useFetch`. ### v1.12.5 * Add string array support for OAuth scope (Thanks @tonka3000!). ### v1.12.4 * Add `tokenResponseParser` and `tokenRefreshResponseParser` in the options of `OAuthService`. * Fix built-in Slack OAuthServices. ### v1.12.3 * Fixed bodyEncoding for some built-in OAuthServices. ### v1.12.2 * Fixed types for `OAuthService.slack`. ### v1.12.1 * Fixed the refresh flow of `OAuthService` that would return outdated tokens. ### v1.12.0 * Removed some default OAuth clientIDs that could not work with generic scopes. * Fixed `withAccessToken` when used in no-view commands. ### v1.11.1 * Fixed Google OAuth configuration. ### v1.11.0 * Added the [OAuth utils](/utilities/oauth.md). ### v1.10.1 * Fix an issue where the values passed to the `reset` function of the `useForm` hook wouldn't be respected. ### v1.10.0 * Add a new [`showFailureToast`](/utilities/functions/showfailuretoast.md) function. ### v1.9.1 * Fix an issue where `useForm`'s `reset` function would not reset the value of some fields (which defeats its purpose...) ### v1.9.0 * Add a new [`useFrecencySorting`](/utilities/react-hooks/usefrecencysorting.md) hook. * Change the default `options.timeout` of `useExec` to 10s. ### v1.8.0 * Add a new [`runAppleScript`](/utilities/functions/runapplescript.md) function. * Change the default `options.timeout` of `useExec` to 10s. ### v1.7.1 Change the signature of [`getProgressIcon`](/utilities/icons/getprogressicon.md) to accept a `Color` in addition to a string for the `options.background`. ### v1.7.0 Change the signature of [`getProgressIcon`](/utilities/icons/getprogressicon.md) to accept a `Color` in addition to a string for the `color`. ### v1.6.0 Added the [`useAI`](/utilities/react-hooks/useai.md) hook. ### v1.4.0 Added the [`useSQL`](/utilities/react-hooks/usesql.md) hook. ### v1.3.1 * Added the `reset` method to `useForm`. ### v1.3.0 * Added the `focus` method to `useForm`. * Added the `input` option to `useExec`. ### v1.2.0 Added [`useExec`](/utilities/react-hooks/useexec.md) and [`useForm`](/utilities/react-hooks/useform.md) hooks. ### v1.1.0 Added [`getFavicon`](/utilities/icons/getfavicon.md) method. ### v1.0.0 First release of the utilities. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.raycast.com/utilities/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.