vue-sanity
v1.0.0
Published
Sanity integration for Vue
Downloads
838
Maintainers
Readme
Composition API methods to incorporate Sanity into a Vue project.
Features
- 🗄 Caching: Query results are cached.
- 💪 TypeScript: Written in TypeScript.
- 📡 Real-time: Supports previews using Sanity listening mode.
- 🖇 Composition API: Vue3/Vue2 support using
vue-demi
. - 📝 SSR support: Compatible with server-side rendering with Nuxt and vanilla Vue.
Quick Start
First install vue-sanity
:
yarn add vue-sanity
# or npm
npm install vue-sanity --save
Now configure Sanity in your root component:
import { useSanityClient } from 'vue-sanity'
export default {
name: 'App',
setup() {
useSanityClient({
projectId: 'myprojectid',
dataset: 'production',
useCdn: process.env.NODE_ENV === 'production',
})
},
}
Then you can use useSanityFetcher
in any child component:
<script>
import { useSanityFetcher } from 'vue-sanity'
export default {
setup() {
const { data: title } = useSanityFetcher('*[_type == "article"][0].title')
// OR use a factory function
const { data: title } = useSanityFetcher(
() => `*[slug.current == ${slug.value}][0].title`
)
return { title }
},
}
</script>
<template>
<div>
<h1>
{{ title }}
</h1>
</div>
</template>
API
useSanityClient
config
These are the options required by
@sanity/client
. For more details, see the Sanity docs.supportPreview
In addition to the config you would normally pass to
@sanity/client
, you can pass a boolean as a second parameter for whether to create a preview client. (Used currently only when listening to real-time data updating.)defaultOptions
You may also pass an object of options that will be passed to any queries you make using
useSanityFetcher
, although of course they will be overridden by any specific options you pass touseSanityFetcher
.
Example
import { useSanityClient } from 'vue-sanity'
export default {
setup() {
useSanityClient(
{
projectId: 'myprojectid',
dataset: 'production',
useCdn: process.env.NODE_ENV === 'production',
},
true // will now create a preview client for use elsewhere
)
},
}
useSanityFetcher
query
A function that retuns a query string. If the return value changes, a new Sanity query will be run and the return value automatically updated.
initialValue
You can provide an initial value for the query result (which will be returned before query completes).mapper
You can provide a function to transform the query result.
options
You can also provide an object of additional options.
- listen: true, false or an object of options to pass to
client.listen
(defaults tofalse
) - strategy: strategy for fetching. Defaults to
both
.:server
: will not refetch if the cache has been populated on SSR:client
: will disable SSR fetching entirely:both
: will fetch on server and refetch when page is loaded
- deduplicate: Whether to de-duplicate identical fetches. If set to
true
, additional fetches will not run unless made after the previous request errors or succeeds. If set to a number, additional fetches will run, but only after this many milliseconds after the previous fetch began.
- listen: true, false or an object of options to pass to
useSanityQuery
If you are using sanity-typed-queries
to define your schema, this is a helper function to reduce boilerplate and explicit typing.
import { useSanityQuery } from 'vue-sanity'
import { builder } from './cms/schemas/author.js'
export default {
setup() {
// title will be typed as Ref<string | null>, with null as a default value
const { data: title } = useSanityQuery(builder.pick('name').first())
// authors will be typed as Ref<string[]>, with an empty array as a default value
const { data: authors } = useSanityQuery(builder.pick('name'))
return { title, authors }
},
}
Example
import { useSanityClient } from 'vue-sanity'
export default {
setup() {
const { data: title } = useSanityFetcher(
// query
() => `*[_type == "article"][0].title`,
// initial value
'Title - Default',
// mapper
result => `Title - ${result}`,
// options
{
listen: true,
clientOnly: true,
}
)
return { title }
},
}
Usage with TypeScript
You can type the return value of useSanityFetcher
in several ways.
// data will be typed as Ref<string | null>
const { data } = useSanityFetcher<string>(
() => `*[_type == "article"][0].title`
)
// data will be typed as Ref<string | number> as a number has been provided as a default value
const { data } = useSanityFetcher<string, number>(
() => `*[_type == "article"][0].title`,
3
)
// data will be typed as Ref<boolean | { value: string }> as it can infer the type
const { data } = useSanityFetcher(
() => `*[_type == "article"][0].title`,
true,
(result: string) => ({ value: result })
)
Inspirations
Projects I've found helpful are:
Contributors
This has been developed to suit my needs but additional use cases and contributions are very welcome.
License
MIT License - Copyright © Daniel Roe