deeplink

Short link generation, click tracking, and OG preview pages for Go. Pluggable processors, Redis or in-memory storage, two dependencies.

Install

go get github.com/yinebebt/deeplink

Usage

service, err := deeplink.New(deeplink.Config{
    BaseURL:     "https://link.example.com",
    Store:       deeplink.NewMemoryStore(),
    TemplateDir: "templates/default",
})
if err != nil {
    log.Fatal(err)
}
service.Register(deeplink.RedirectProcessor{})

// Mount alongside your own routes.
mux := http.NewServeMux()
mux.Handle("/", service.Handler())
mux.HandleFunc("GET /hello", yourHandler)

log.Fatal(http.ListenAndServe(":8090", mux))

Create a short link:

curl -X POST http://localhost:8090/shorten \
  -H 'Content-Type: application/json' \
  -d '{"type":"redirect","url":"https://example.com/docs","title":"Docs"}'

Open the returned short_url in a browser.

Custom processors

Implement Processor:

type Processor interface {
    Type() string
    Process(ctx context.Context, link *Link) error
}

For custom template data, also implement Previewer:

type Previewer interface {
    Preview(link *Link) any
}

See example/custom for a working custom processor with tests.

Standalone server

A ready-to-run Redis-backed server is included:

docker compose up -d
go run ./cmd/deeplink

HTTP routes

When any store URL is set (AndroidStoreURL, IOSStoreURL, WebFallbackURL), these are also registered:

For iOS Universal Links and Android App Links, place your apple-app-site-association and assetlinks.json files in <TemplateDir>/.well-known/.

Configuration

Environment variables for cmd/deeplink:

Templates

The default templates in templates/default/ use these fields from Link:

To customize, copy templates/default/ and set TemplateDir in config.

Link preview metadata

Preview pages emit standard Open Graph, Twitter Card, and fediverse meta tags consumed by every platform that scrapes link previews. Every tag is gated on its source value: empty fields are not emitted, so scrapers never see content="" warnings.

Per-link fields (Link)

Service-wide fields (Config)

Example payload

curl -X POST http://localhost:8090/shorten \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "redirect",
    "url": "https://example.com/posts/launch",
    "title": "We just launched",
    "description": "What is new in v2",
    "image_url": "https://cdn.example.com/og/launch.png",
    "image_width": 1200,
    "image_height": 630,
    "image_alt": "v2 launch cover",
    "og_type": "article"
  }'

Preview pages also emit <meta name="robots" content="noindex,follow"> so short links do not compete with the destination URL in search rankings.

Dashboard

A standalone React + TypeScript dashboard lives in web/. It talks to the Go service over HTTP and shares the repo's root .env.

cd web
npm install
npm run dev     # http://localhost:5173

One env var configures it (in root .env):

VITE_API_URL=http://localhost:8091

• npm run dev uses it as the Vite proxy target only — the browser hits :5173, so there is no CORS and the scheme is optional.
• npm run build bakes it into the bundle as an absolute base, so the static dist can be hosted on any origin. Scheme required.

The dashboard reads the API key from localStorage (deeplink.apiKey) and sends it as X-API-Key on mutating requests, so set DEEPLINK_API_KEY server-side to enable enforcement. When the SPA runs on a different origin in production, add that origin to DEEPLINK_ALLOWED_ORIGINS.

Development

go test ./...          # run tests
go run ./cmd/deeplink  # run standalone server (needs Redis)

License

MIT