SkyState

Quickstart ​

This guide takes you from a fresh account to a working SkyState integration. 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, public settings, and client-visible catalog or inventory values.

Estimated time: 5 minutes.

Step 1: Create Your Account ​

Open https://console.skystate.io in your browser and sign in with your email or a supported identity provider. 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 public-state 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 shows an Account section with token status, display name, email, account ID, 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 globally unique.

From the console:

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

Step 5: Explore the Onboarding Wizard ​

Run:

bash
sky onboarding

The CLI will:

  1. Sign in or reuse your stored session.
  2. Fetch your projects and let you select one, or create a new one inline if you have none.
  3. Ask which stack you want to wire first.
  4. For Node.js and curl examples, ask whether to use an existing project API key or create a new one.
  5. Print the starter snippet for that stack and exit.

It does not write files. If you want a local API key for your own secret-management flow, create one with:

bash
sky project keys create --project my-app

Step 6: 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 7: 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.

Push to the other environments when you are ready:

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

Or promote across environments without re-uploading a file:

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

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 directly in the console editor and save - each save creates a new version.

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 ReactDOM from 'react-dom/client';
import { SkyStateProvider } from '@skystate/react';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <SkyStateProvider
    account="acc_example"
    project="my-app"
    environment="development"
  >
    <App />
  </SkyStateProvider>
);

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!',
  });
  const publicState = usePublicState();

  if (publicState.status === 'loading' || !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',
  project: 'my-app',
  environment: 'production',
});

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

What's Next ​