Pular para o conteúdo principal

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 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 API

O 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.

Default export

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 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.

Versão da API

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().

Identificador do workspace

Atualmente, a versão 2 das APIs do Starlight só identificam áreas de trabalho utilizando seus IDs. O suporte à slugs 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 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. Você vai aprender como fazer requisições nas próximas páginas, mas aqui vai um exemplo de como requisitar uma entrada de um modelo de slug 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 utilizam a Fetch API por baixo dos panos e retornam Promises. Isso quer dizer que você também pode usar a sintaxe .then() ao invés de async/await, se preferir.

nota sobre async/await nesse guia

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 inserir os exemplos numa 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()

Configurando as requisições do SDK​

Como comentamos na seção anterior, o SDK utiliza a Fetch API para fazer todas as suas requisições. Isso quer dizer que você pode passar opções para modificar como a função fetch faz uma requisição:

import Starlight from '@starlightcms/js-sdk'

// O último parâmetro é um objeto de opções do fetch
const response = await Starlight.posts.entries.list({ page: 1 }, { cache: 'force-cache' })

Todos os métodos do SDK que fazem requisições às APIs do Starlight aceitam um objeto de configurações do fetch como último parâmetro. Esse objeto será repassado diretamente à função fetch sem nenhuma modificação.

Dê uma olhada na página da MDN sobre as opções da função fetch (em inglês) para aprender mais sobre todas as opções disponíveis.

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 slug 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.