Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/superfly/sprites-go/llms.txt

Use this file to discover all available pages before exploring further.

The FS interface exposes a sprite’s filesystem to your Go program. It satisfies the standard library’s io/fs.FS, fs.StatFS, fs.ReadFileFS, and fs.ReadDirFS interfaces, so it works with any code that accepts those types. Write operations — creating files, directories, renaming, copying, and changing permissions — are added on top. Obtain an FS value by calling Sprite.Filesystem() or Sprite.FilesystemAt(). 
// Root at "/"
fsys := sprite.Filesystem()

// Root at a specific directory
fsys := sprite.FilesystemAt("/app")

​
Interface definition

type FS interface {
    fs.FS         // Open(name string) (fs.File, error)
    fs.StatFS     // Stat(name string) (fs.FileInfo, error)
    fs.ReadFileFS // ReadFile(name string) ([]byte, error)
    fs.ReadDirFS  // ReadDir(name string) ([]DirEntry, error)

    WriteFile(name string, data []byte, perm fs.FileMode) error
    Mkdir(name string, perm fs.FileMode) error
    MkdirAll(path string, perm fs.FileMode) error
    Remove(name string) error
    RemoveAll(path string) error
    Rename(oldname, newname string) error
    Copy(src, dst string) error
    Chmod(name string, mode fs.FileMode) error

    WriteFileContext(ctx context.Context, name string, data []byte, perm fs.FileMode) error
    RemoveContext(ctx context.Context, name string) error
    RemoveAllContext(ctx context.Context, path string) error
    CopyContext(ctx context.Context, src, dst string) error
    ChmodContext(ctx context.Context, name string, mode fs.FileMode) error
}

​
Read operations

​
Open

Open(name string) (fs.File, error)
Opens the named file or directory for reading. Satisfies io/fs.FS. Returns an fs.File which is an fs.ReadDirFile for directories.
​
name
string
required
Path to the file or directory. Must not start with / when using the standard fs.FS convention.
​
fs.File
fs.File
Open file handle. Call Close() when done.
​
error
error
*fs.PathError wrapping fs.ErrNotExist if the path does not exist.

​
Stat

Stat(name string) (fs.FileInfo, error)
Returns metadata for the named file or directory without reading its contents. Satisfies fs.StatFS.
​
name
string
required
Path to stat.
​
fs.FileInfo
fs.FileInfo
File metadata including name, size, mode, modification time, and whether it is a directory.
​
error
error
*fs.PathError wrapping fs.ErrNotExist if the path does not exist.
info, err := fsys.Stat("config/app.yaml")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s: %d bytes\n", info.Name(), info.Size())

​
ReadFile

ReadFile(name string) ([]byte, error)
Reads and returns the entire content of the named file. Satisfies fs.ReadFileFS.
​
name
string
required
Path to the file to read.
​
[]byte
[]byte
Complete file contents.
​
error
error
*fs.PathError if the file cannot be read.
data, err := fsys.ReadFile("config/app.yaml")
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(data))

​
ReadDir

ReadDir(name string) ([]fs.DirEntry, error)
Lists the contents of the named directory. Returns entries sorted by filename. Satisfies fs.ReadDirFS.
​
name
string
required
Path to the directory to list.
​
[]fs.DirEntry
[]fs.DirEntry
Directory entries. Each entry exposes Name(), IsDir(), Type(), and Info().
​
error
error
*fs.PathError wrapping fs.ErrNotExist if the directory does not exist.
entries, err := fsys.ReadDir("logs")
if err != nil {
    log.Fatal(err)
}
for _, e := range entries {
    fmt.Println(e.Name(), e.IsDir())
}

​
Write operations

​
WriteFile

WriteFile(name string, data []byte, perm fs.FileMode) error
Writes data to the named file, creating it if it does not exist and overwriting it if it does. Parent directories are created automatically. Uses a background context; prefer WriteFileContext for cancellation support.
​
name
string
required
Destination path.
​
data
[]byte
required
Bytes to write.
​
perm
fs.FileMode
required
Permission bits for the file (e.g., 0644).
err := fsys.WriteFile("config/app.yaml", []byte("key: value\n"), 0644)

​
Mkdir

Mkdir(name string, perm fs.FileMode) error
Creates the named directory. Parent directories are created automatically (behaves like MkdirAll).
​
name
string
required
Path of the directory to create.
​
perm
fs.FileMode
required
Permission bits (e.g., 0755).

​
MkdirAll

MkdirAll(path string, perm fs.FileMode) error
Creates the directory named by path, including any necessary parent directories. Equivalent to Mkdir in the current implementation.
​
path
string
required
Full directory path to create.
​
perm
fs.FileMode
required
Permission bits.

​
Remove

Remove(name string) error
Removes the named file or empty directory.
​
name
string
required
Path to remove.
​
error
error
*fs.PathError wrapping fs.ErrNotExist if the path does not exist.

​
RemoveAll

RemoveAll(path string) error
Removes the named file or directory and all its contents recursively. Succeeds even if the path does not exist.
​
path
string
required
Path to remove recursively.

​
Rename

Rename(oldname, newname string) error
Renames (moves) oldname to newname. Works for both files and directories.
​
oldname
string
required
Current path.
​
newname
string
required
Destination path.
err := fsys.Rename("data/old.csv", "data/archive/old.csv")

​
Copy

Copy(src, dst string) error
Copies src to dst. Directories are copied recursively.
​
src
string
required
Source file or directory path.
​
dst
string
required
Destination path.

​
Chmod

Chmod(name string, mode fs.FileMode) error
Changes the permission bits of the named file or directory.
​
name
string
required
Path to update.
​
mode
fs.FileMode
required
New permission bits (e.g., 0755).

​
Context variants

Each write method that may be slow has a context-aware counterpart. Pass a context with a deadline or cancellation to abort long-running operations.

​
WriteFileContext

WriteFileContext(ctx context.Context, name string, data []byte, perm fs.FileMode) error
​
ctx
context.Context
required
Context for the HTTP request. Cancelling aborts the upload.
​
name
string
required
Destination path.
​
data
[]byte
required
Bytes to write.
​
perm
fs.FileMode
required
Permission bits.
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
err := fsys.WriteFileContext(ctx, "uploads/large.bin", data, 0644)

​
RemoveContext

RemoveContext(ctx context.Context, name string) error
Context-aware variant of Remove.
​
ctx
context.Context
required
Context for the request.
​
name
string
required
Path to remove.

​
RemoveAllContext

RemoveAllContext(ctx context.Context, path string) error
Context-aware variant of RemoveAll.
​
ctx
context.Context
required
Context for the request.
​
path
string
required
Path to remove recursively.

​
CopyContext

CopyContext(ctx context.Context, src, dst string) error
Context-aware variant of Copy.
​
ctx
context.Context
required
Context for the request.
​
src
string
required
Source path.
​
dst
string
required
Destination path.

​
ChmodContext

ChmodContext(ctx context.Context, name string, mode fs.FileMode) error
Context-aware variant of Chmod.
​
ctx
context.Context
required
Context for the request.
​
name
string
required
Path to update.
​
mode
fs.FileMode
required
New permission bits.

​
Usage with standard library

Because FS implements io/fs.FS, you can pass it to any standard library function that accepts that interface: 
fsys := sprite.Filesystem()

// Walk the entire tree
err := fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
    if err != nil {
        return err
    }
    fmt.Println(path)
    return nil
})

// Read a file with fs.ReadFile
data, err := fs.ReadFile(fsys, "config/app.yaml")

Build docs developers (and LLMs) love

Get started for freeTalk to us