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-appYou 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.