Quickstart with Legit SDK
This guide will help you create your first Legit-backed project and understand the basics of versioned file operations.
Next.js
Starter Command
npx @legit-sdk/create-next-starter my-app// TODO: Host these example projects so users can explore them live.
You can install a Legit x Next.js Starter with this command
Manual Guide
1. Install the SDK
npm i @legit-sdk/react2. Add the LegitProvider to your app
The provider sets up the Legit environment for all nested components. Since SSR frameworks use server components by default, make sure to create a client component wrapper.
// app/LegitProviderComponent.tsx (Next.js, app router)
'use client';
import { ReactNode } from 'react';
import { LegitProvider } from '@legit-sdk/react';
export default function LegitProviderComponent(props: { children: ReactNode}): ReactNode {
return <LegitProvider>
{ props.children }
</LegitProvider>
}Then, use it in your app layout:
// app/layout.tsx (Next.js, app router)
import React from 'react';
import LegitProviderComponent from './LegitProviderComponent';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<LegitProviderComponent>
{children}
</LegitProviderComponent>
</body>
</html>
)
}3. Use the useLegitFile hook
The hook gives you access to:
- data → current text of a file
- setData(value) → commit new changes
- history → array of past commits
The hook must be used inside a client component wrapped by LegitProvider. Add 'use client' (Next.js) to the desired component.
// app/page.tsx
'use client';
import React, { useState, useEffect } from 'react';
import { useLegitFile } from '@legit-sdk/react';
const FILE_PATH = '/notes.txt';
const INITIAL_TEXT = 'Hello from Legit đź‘‹';
export default function Editor() {
const { data, setData, history, loading, error } = useLegitFile(FILE_PATH, { initialData: INITIAL_TEXT });
const [text, setText] = useState<string | undefined>(undefined);
// Initialize with text from LegitFs
useEffect(() => {
if (!text) {
// eslint-disable-next-line react-hooks/set-state-in-effect
setText(data || undefined);
}
}, [loading, data, text, loading]);
if (loading) return <div>Loading Legit...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<div style={{ padding: 20 }}>
<h2>đź“ť Legit Editor</h2>
<p>
{loading ? 'Loading...' : 'Loaded'}
</p>
<input
className="border border-gray-300 rounded-md p-2"
value={text}
onChange={(e) => setText(e.target.value)}
onBlur={() => text && setData(text)}
/>
<pre>{JSON.stringify(history, null, 2)}</pre>
</div>
);
}Next steps:
- React Wrapper — Full documentation for the React wrapper
- React Wrapper API Reference — Full documentation for the React wrapper API
- Legit SDK Examples — Explore Legit SDK Starters and Examples
- Filesystem API Reference — See all available paths in the file system
Environment Compatibility
Legit SDK works in many environments:
- Operating Systems: macOS, Linux, Windows
- Languages: Node.js, Python, Java (more coming)
- Containers / Sandboxed Environments: Docker, serverless, cloud VMs
It works everywhere because it operates on a filesystem abstraction. Any environment that supports standard filesystem operations can run it. In this getting started you can choose between SSR, React, Vanilla JS, Vue, or Svelte.