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. Public state is a good fit for application config, feature flags, settings, and catalog or inventory values.

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 the token at ~/.config/skystate/token.json.

To confirm you are authenticated:

bash
sky status

The output starts with an Auth block that shows which credential serves each role. The Account Ops line is the credential used for account commands, and the Project Ops line is the credential used for project data commands. Below that, the Login section shows token status, display name, account ID, email, subscription tier, and usage when available. The API key section shows any key loaded from SKYSTATE_API_KEY or .env.local when present.

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: Diff / Promote ​

Compare two environments to see what would change:

bash
sky state public diff --project my-app --from development --to staging

Then promote state from one environment to another:

bash
sky state public promote --project my-app --from development --to staging

On the first run staging is empty, so the diff shows all of development as additions and promote seeds staging at version 1.

Step 8: Verify in the Console ​

Open https://console.skystate.io, navigate to your project, and click the Public state tab. You should see your state displayed under the Development environment.

You can edit values in the console editor and save - each save creates a new version. The tab also has a diff view for comparing your current edits against an earlier version, including versions from other environments.

Step 9: 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. Call usePublicState() with no arguments for public-state loading and error status.

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 ​