# 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.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: 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: ``` GET https://developers.raycast.com/utilities/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.