Cliente
Um cliente do Starlight provê, dentre outras coisas, vários métodos para requisitar dados de uma área de trabalho no
Starlight. Na seção de configuração, por exemplo, você utilizou o método configure()
para indicar qual
área de trabalhoÁreas de trabalho representam sites ou aplicativos no Starlight. Todo conteúdo pertence à uma área de trabalho. o SDK deve utilizar nas requisições.
Existem duas maneiras de interagir com um cliente do Starlight:
- Utilizando o cliente global do JS SDK; ou
- Criando uma nova instância do cliente
Cliente global do SDK
Visualizar na APIO JS SDK provê um cliente pré-configurado globalmente para usar na sua aplicação. Para usá-lo, basta importar o default export do SDK:
import Starlight from '@starlightcms/js-sdk'
Você pode usar esse import em qualquer lugar da sua aplicação. Como esse cliente é global e único, você só precisa configurá-lo uma vez, como explicado na seção de configuração.
Como o cliente global do SDK é o objeto exportado por padrão pelo módulo do SDK, você pode chamá-lo de qualquer coisa, não apenas Starlight. Por exemplo, você pode importá-lo com um nome mais explicativo caso use mais de um cliente na sua aplicação:
import BlogClient from '@starlightcms/js-sdk'
Configurando o cliente global
Antes de começar a utilizar o cliente global do SDK, você precisa configurar qual área de trabalhoÁreas de trabalho representam sites ou aplicativos no Starlight. Todo conteúdo pertence à uma área de trabalho. deve ser utilizada
para requisitar dados. Utilize o método configure()
do StarlightClient para isso:
import Starlight from '@starlightcms/js-sdk'
Starlight.configure({
workspace: '1234567890'
})
Você pode verificar todas as opções disponíveis na página da API sobre o StarlightConfig.
A configuração do cliente global só precisa ser feita uma vez, idealmente no início do ciclo de vida da sua aplicação.
Por exemplo, em aplicações React, você pode configurar o cliente global no mesmo arquivo onde você instancia a raíz
da sua aplicação usando ReactDOM.createRoot()
.
A página do método configure()
na API contém um exemplo disso.
Por padrão, o SDK requisita dados do Starlight utilizando a versão 2 da Query API. Isso pode ser configurado
alterando o parâmetro baseUrl
ao usar o método configure()
.
Atualmente, a versão 2 das APIs do Starlight só identificam áreas de trabalho utilizando seus IDs. O suporte à slugsSlugs são identificadores únicos usados por todos os tipos de dado no Starlight. São utilizados em URLs para identificar dados. ainda não foi implementado.
Você pode visualizar o ID de uma área de trabalho na interface de administração do Starlight, abaixo do nome da área de trabalho no menu ao lado esquerdo da tela.
Criando um cliente
Caso sua aplicação precise requisitar dados de mais de uma área de trabalhoÁreas de trabalho representam sites ou aplicativos no Starlight. Todo conteúdo pertence à uma área de trabalho. do Starlight, você pode criar novos clientes:
import { makeStarlightClient } from '@starlightcms/js-sdk'
const NewClient = makeStarlightClient({
workspace: '1234567890'
})
A função makeStarlightClient()
recebe os mesmos parâmetros que o método
configure()
explicado na seção acima, mas retorna uma instância única, separada do cliente global. Depois de criado,
você pode exportar esse cliente para ser usado no resto da sua aplicação.
Requisições retornam Promises
Todo cliente do SDK provê os mesmos métodos para requisição de dados de sua respectiva área de trabalhoÁreas de trabalho representam sites ou aplicativos no Starlight. Todo conteúdo pertence à uma área de trabalho.. Você vai
aprender como fazer requisições nas próximas páginas, mas aqui vai um exemplo de como requisitar uma entradaEntradas são instâncias de um modelo, como uma postagem de um blog ou uma edição de uma revista. de um
modeloModelos representam dados que se repetem, como posts de um blog ou revistas. de slugSlugs são identificadores únicos usados por todos os tipos de dado no Starlight. São utilizados em URLs para identificar dados. posts
:
import Starlight from '@starlightcms/js-sdk'const requestEntry = async (slug) => { // response é do tipo StarlightItemResponse<Entry> const response = await Starlight.posts.entries.get(slug) // O parâmetro data é do tipo Entry return response.data}const entry = await requestEntry('hello-world')
Note que usamos a palavra-chave async
do JavaScript ao utilizar o método get()
na linha 5. Fizemos isso porque
todos os métodos do SDK que fazem requisições ao Starlight retornam Promises. Isso quer dizer que você também pode
usar a sintaxe .then()
ao invés de async/await
, se preferir.
A maioria dos exemplos desse guia usa a sintaxe async/await
fora de funções async
. Isso só é possível em ambientes
que dão suporte a top-level await.
Todos os navegadores modernos dão suporte a esse recurso, mas caso você tenha problemas rodando os exemplos desse guia
localmente, basta colocar os exemplos dentro de uma função assíncrona:
import Starlight from '@starlightcms/js-sdk'
// ❗ Talvez esse código não funcione no seu ambiente local:
const response = await Starlight.posts.entries.list()
// ✅ Resolvendo o problema usando funções assíncronas:
const requestPosts = async () => {
const response = await Starlight.posts.entries.list()
// Agora você pode fazer o que quiser com os dados.
// Nesse caso, vamos apenas imprimir as postagens no console:
console.log(response.data)
}
// Não esqueça de chamar sua função!
requestPosts()
Tratando erros nas requisições
O exemplo acima é útil, mas não deve ser usado em ambientes de produção, já que sua aplicação pode quebrar caso um erro aconteça no processo de requisição da entrada, ou caso uma entrada com o slugSlugs são identificadores únicos usados por todos os tipos de dado no Starlight. São utilizados em URLs para identificar dados. requisitado não exista.
Para resolver esse problema, você pode usar try/catch
ou .catch()
nas requisições. Todos os métodos do SDK que fazem
requisições retornam um erro do tipo StarlightError
quando algo errado acontece, inclusive no caso do Starlight não
encontrar o dado requisitado (404). Por exemplo, podemos melhorar a função acima:
import Starlight, { StarlightError } from '@starlightcms/js-sdk'
// Retorna a entrada requisitada ou false se ela não existir.
const requestEntry = async (slug) => {
try {
const response = await Starlight.posts.entries.get(slug)
return response.data
} catch (error) {
if (error instanceof StarlightError && error.response.status === 404) {
// O Starlight não encontrou uma entrada com esse slug.
return false
}
// Se o erro não for 404, apenas o "jogamos" novamente.
// Nesse caso, quem usar essa função se responsabiliza em tratar esse erro.
throw error
}
}
// Caso `entry` seja "false", essa entrada não existe.
// Caso exista, `entry` será do tipo Entry.
const entry = await requestEntry('hello-world')
O StarlightError é um objeto com um parâmetro response
, que é a resposta retornada pelo método fetch
do navegador
(ou do Node, caso você faça a requisição do lado do servidor). Para mais informações sobre esse erro, dê uma olhada
nessa página do guia sobre respostas e
nessa página da API que detalha o StarlightError.