Quickstart

This guide takes you from a fresh account to a working SkyState integration. By the end you will have pushed a config to SkyState and read it back from a React app.

Estimated time: 5 minutes.

---

Step 1: Create Your Account

Open https://app.skystate.io in your browser and click Sign in with GitHub. Authorize the OAuth app. SkyState will create your account and redirect you to the dashboard.

Your account is identified by a slug — a short lowercase identifier derived from your GitHub username. You will see it in the dashboard and in public config URLs.

---

Step 2: Install the CLI

npm install -g @skystate/cli

Verify the installation:

skystate --version

---

Step 3: Log In

skystate login

This opens your default browser at the SkyState login page. After you authorize, copy the token shown on the page and paste it back into the terminal prompt. The CLI stores the token at ~/.config/skystate/credentials.json.

To confirm you are authenticated:

skystate status

Expected output:

email        you@example.com
name         Your Name
slug         your-slug
sso provider github
tier         free
projects     0/3
api requests 0/200

---

Step 4: Create a Project

Projects are the top-level containers for your configs. Create one from the dashboard or from the CLI.

From the CLI:

skystate project create "My App" my-app

The first argument is the display name; the second is the slug. Slugs must be lowercase alphanumeric with hyphens and must be unique within your account.

From the dashboard:

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

---

Step 5: Initialize Your Repository

Inside the repository you want to connect, run:

skystate init

The CLI will:

1. Fetch your projects and display a numbered list.
2. Ask you to select a project (or create a new one inline).
3. Generate a dev API key scoped to the development environment.
4. Write skystate.json to the repository root — commit this file.
5. Write SKYSTATE_DEV_KEY=sk_dev_... to .env — do not commit this file.
6. Offer to add .env to .gitignore if it is not already there.

After init completes, your repository contains:

skystate.json   ← project binding, safe to commit
.env            ← dev key, add to .gitignore

---

Step 6: Write Your First Config

Create a JSON file that describes your app's remote configuration:

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

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

---

Step 7: Push the Config

skystate push config.json --env development

Expected output:

Pushed config to my-app/development
  1.0.0

The first push always creates version 1.0.0. Subsequent pushes auto-detect the appropriate version bump based on what changed:

• Keys removed or types changed → major bump
• Keys added → minor bump
• Values changed → patch bump

Push to the other environments when you are ready:

skystate push config.json --env staging
skystate push config.json --env production

Or promote across environments without re-uploading a file:

skystate promote --from development --to staging
skystate promote --from staging --to production

---

Step 8: Verify in the Dashboard

Open https://app.skystate.io, navigate to your project, and click the Remote Config tab. You should see your config displayed with version 1.0.0 under the Development environment.

You can edit values directly in the dashboard editor and save — each save creates a new version.

---

Step 9: Read the Config in Your App

React

Install the React SDK:

npm install @skystate/react

Wrap your application with SkyStateProvider and pass your project slug, environment, and dev key:

// main.tsx
import { SkyStateProvider } from '@skystate/react';

const devKey = import.meta.env.VITE_SKYSTATE_DEV_KEY;

ReactDOM.createRoot(document.getElementById('root')!).render(
  <SkyStateProvider
    projectSlug="my-app"
    environment="development"
    devKey={devKey}
  >
    <App />
  </SkyStateProvider>
);

In your .env file, add:

VITE_SKYSTATE_DEV_KEY=sk_dev_...

Vite exposes variables prefixed with VITE_ to the client bundle automatically.

Use the useProjectConfig hook to read individual config keys:

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

export function Banner() {
  const { data: enabled, isLoading } = useProjectConfig<boolean>(
    'banner.enabled',
    false,
  );
  const { data: text } = useProjectConfig<string>(
    'banner.text',
    'Welcome!',
  );

  if (isLoading || !enabled) return null;

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

The hook returns { data, isLoading, error }. On mount, data is the default value you provide and isLoading is true. Once the fetch resolves, data is updated to the server value.

Vanilla JavaScript / Node.js

Install the core SDK:

npm install @skystate/core

import { createSkyStateClient } from '@skystate/core';

const client = createSkyStateClient({
  projectSlug: 'my-app',
  environment: 'production',
});

const value = await client.get<boolean>('maintenance.enabled', false);
console.log(value); // false

---

What's Next

• Learn about Core Concepts — environments, versioning, and how configs are scoped.
• Read the full CLI Reference for all available commands.
• Explore the React SDK and Core SDK API references.
• Understand Billing and Tiers if you need higher limits.