SkyState

Quickstart ​

This guide takes you from a fresh account to storing and retrieving data with SkyState. By the end you will have pushed public state to SkyState and read it back from a React app. See what public state is for.

Estimated time: 5 minutes.

Step 1: Create Your Account ​

Open https://console.skystate.io and sign in with Google or GitHub. SkyState will create your account and redirect you to the console.

Your account is identified in routes by an account ID such as acc_.... You will see it in the console, sky status, SDK configuration, and API URLs.

Step 2: Install the CLI ​

bash
npm install -g skystate

Step 3: Log In ​

bash
sky login

This opens your default browser at the SkyState login page. After you authorize, the CLI stores your session locally and keeps you signed in for the commands that follow.

To confirm you are authenticated:

bash
sky status

Step 4: Create a Project ​

Projects are the top-level containers for your public and user state. Create one from the console or from the CLI.

From the CLI:

bash
sky project create "My App" my-app

The first argument is the display name; the second is the slug. Slugs must use lowercase letters, numbers, and hyphens, and must be unique among your own projects.

From the console:

Click New Project on the Projects page at https://console.skystate.io, enter a name and slug, and save.

Step 5: Write Your First Public State ​

Create a JSON file that describes public values your app can read at runtime:

bash
cat > config.json << 'EOF'
{
  "maintenance": { "enabled": false },
  "banner": {
    "enabled": true,
    "text": "Welcome to My App!"
  },
  "features": { "darkMode": false },
  "limits": { "maxUploadMb": 10 },
  "inventory": { "starterKitAvailable": true }
}
EOF

Values can be any JSON type: booleans, strings, numbers, objects, or arrays. Each top-level property becomes a key your SDK can read individually.

Step 6: Push Public State ​

bash
sky state public push --project my-app --file config.json --env development

The first push creates version 1. Each subsequent push increments the version number. If breaking changes are detected (key removals or type changes), the CLI reports the count and prompts for confirmation before proceeding.

Step 7: Read Public State in Your App ​

React ​

Install the React SDK in your project:

bash
npm install @skystate/react

Wrap your application with SkyStateProvider:

tsx
// main.tsx
import { createRoot } from 'react-dom/client';
import { SkyStateProvider } from '@skystate/react';
import App from './App';

function Root() {
  return (
    <SkyStateProvider
      account="acc_example" // Replace acc_example with your account ID from `sky status`
      project="my-app"
      environment="development"
    >
      <App />
    </SkyStateProvider>
  );
}

createRoot(document.getElementById('root')!).render(<Root />);

Use usePublicState to read individual public-state keys:

tsx
// Banner.tsx
import { usePublicState } from '@skystate/react';

export function Banner() {
  const { value: banner } = usePublicState('banner', {
    enabled: false,
    text: 'Welcome!',
  });

  if (!banner?.enabled) return null;

  return <div className="banner">{banner.text}</div>;
}

Keyed usePublicState returns { value } with the current value or fallback. Loading and error status comes from useStatus().health.

Vanilla JavaScript / Node.js ​

Install the core SDK in your project:

bash
npm install @skystate/core
ts
import { createSkyStateClient } from '@skystate/core';

const client = createSkyStateClient({
  account: 'acc_example', // Replace acc_example with your account ID from `sky status`
  project: 'my-app',
  environment: 'development',
});

await client.init();
const maintenance = client.publicState.get('maintenance', { enabled: false });
console.log(maintenance); // { enabled: false }

What's Next ​