DOCSEARCHbyAlgolia
Submit Docs

Limen Documentation

repository·master·Indexed 19 days ago

https://github.com/thecodearcher/limen

A modern, composable authentication library for Go featuring a plugin-first architecture. Limen provides core session management and security primitives, with modular plugins for authentication methods like OAuth and passwords. It includes a TypeScript SDK (limen-auth) with reactive session tracking and framework adapters for React, Vue, Svelte, and Solid, as well as a CLI for generating Go models and SQL migrations for PostgreSQL and MySQL.

Tokens
114.5K
Snippets
435
Records
580
Agent score
66%

What's inside Limen

  1. Limen CLI Command Structure and Global Flags

    master

    The Limen CLI uses a nested command structure:

    limen [global-flags] generate <subcommand> [flags]

    Global Flags

    All commands accept the following flag:

    • --schemas, -s: Path to the schemas file generated by Limen (default: ./.limen/schemas.json)

    Available Subcommands

    • generate models: Generates Go structs from schemas.
    • generate migrations: Generates SQL migration files from schemas.

  3. Retrieve authenticated user session with auth.GetSession(r)

    master
    In custom endpoints (such as the GET /api/profile endpoint found in the basic and gin examples), you can access the authenticated user session by calling auth.GetSession(r). This allows you to read session data outside of Limen's built-in authentication routes.

  4. How Limen's plugin-first architecture works

    master

    Limen is designed as a modular authentication library. The core package provides the essential interfaces, session management, and security primitives, but it does not include specific authentication methods by default.

    Instead, authentication methods (like OAuth 2.0 or Credential/Password) are implemented as separate Go modules. This allows you to compose a custom authentication stack by importing only the plugins and adapters you need, keeping your application's dependency tree lean.

  6. Install Limen and its plugins

    master

    Limen uses a plugin-first architecture. To use it, you must install the core library and then explicitly install the specific adapters and plugins your application requires via go get.

    1. Install the core library: go get github.com/thecodearcher/limen

    2. Install an adapter (e.g., GORM): go get github.com/thecodearcher/limen/adapters/gorm

    3. Install a plugin (e.g., Credential/Password): go get github.com/thecodearcher/limen/plugins/credential-password

    go get github.com/thecodearcher/limen
go get github.com/thecodearcher/limen/adapters/gorm
go get github.com/thecodearcher/limen/plugins/credential-password

  7. Install the Limen CLI

    master

    The Limen CLI provides code generation for Go models and SQL migrations based on Limen schema definitions.

    Prerequisites

    • Go 1.25 or later
    • A Limen project with an initialized schemas file (.limen/schemas.json)

    Installation Methods

    Build from source:

    cd cmd/limen
go build -o limen

    Install globally via Go:

    go install github.com/thecodearcher/limen/cmd/limen@latest
    go install github.com/thecodearcher/limen/cmd/limen@latest

  8. Quick start with limen-auth

    master

    Initialize an authentication client using createAuthClient. You must provide a baseURL pointing to your Limen server origin and a list of plugins (such as credentialPasswordPlugin).

    Key features:

    • Reactive Session: The auth.$session property is a reactive store that tracks the current user. It automatically stays in sync across browser tabs and updates on sign-in/sign-out.
    • Automatic Mutations: Calling methods like signIn.credential or signout automatically updates the $session store without requiring manual refetching.
    • Framework Adapters: For React, Vue, Svelte, or Solid, use the specific entry points (limen-auth/react, etc.) to access a useSession() hook.
    import { createAuthClient } from "limen-auth";
import { credentialPasswordPlugin } from "limen-auth/plugins/credential";

export const auth = createAuthClient({
  baseURL: "http://localhost:8080", // your Limen server origin
  plugins: [credentialPasswordPlugin()],
});

// `auth.$session` is a reactive store for the current user
auth.$session.subscribe(({ data, isPending }) => {
  if (isPending) return;
  console.log(data ? `Signed in as ${data.user.email}` : "Signed out!");
});

// Mutations update `$session` automatically
await auth.signIn.credential({ credential: "ada@example.com", password: "secret" });
await auth.signout();

  9. Run Limen examples

    master

    Limen provides several standalone Go module examples that demonstrate different features, adapters, and plugins. To run these examples from the repository root, you must have a running PostgreSQL database and provide the DATABASE_URL environment variable.

    Note that the examples use go.work for local module resolution within the repository.

    # Example: Running the basic example
DATABASE_URL="postgres://user:pass@localhost:5432/limen?sslmode=disable" go run ./examples/basic

# Example: Running the OAuth Google example
DATABASE_URL="postgres://..." GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... go run ./examples/oauth-google

  10. Apply generated migrations

    master

    The Limen CLI only generates the SQL files; it does not apply them to the database. You must use a migration tool to run the files in your output directory.

    Using golang-migrate:

    migrate -path ./migrations \
  -database "postgres://user:pass@localhost/db?sslmode=disable" \
  up

    Using goose:

    goose -dir ./migrations postgres "postgres://user:pass@localhost/db?sslmode=disable" up
    migrate -path ./migrations -database "postgres://user:pass@localhost/db?sslmode=disable" up

  11. Prerequisites for running Limen examples

    master

    To run the provided Limen examples, ensure your environment meets the following requirements:

    • Go version: 1.25 or higher
    • Database: A running PostgreSQL instance
    • Environment Variable: DATABASE_URL must be set (e.g., postgres://user:pass@localhost:5432/limen?sslmode=disable)

  12. Quick Start with Limen and GORM

    master

    To initialize Limen, you need a database connection, a GORM adapter, and a list of plugins. You can provide the Secret directly in the limen.Config struct or via the LIMEN_SECRET environment variable.

    Limen provides an auth.Handler() which can be mounted to any standard Go http.ServeMux or compatible router.

    package main

import (
	"log"
	"net/http"

	"gorm.io/driver/postgres"
	"gorm.io/gorm"

	"github.com/thecodearcher/limen"
	gormadapter "github.com/thecodearcher/limen/adapters/gorm"
	credentialpassword "github.com/thecodearcher/limen/plugins/credential-password"
)

func main() {
	db, err := gorm.Open(postgres.Open("your-dsn"), &gorm.Config{})
	if err != nil {
		log.Fatal(err)
	}

	auth, err := limen.New(&limen.Config{
		BaseURL:  "http://localhost:8080",
		Database: gormadapter.New(db),
		Secret:   []byte("your-32-byte-secret-key-here!!!!"),
		Plugins: []limen.Plugin{
			credentialpassword.New(),
		},
	})
	if err != nil {
		log.Fatal(err)
	}

	mux := http.NewServeMux()
	mux.Handle("/api/auth/", auth.Handler())

	log.Println("listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}