Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Slugs

View as Markdownllms.txt

A slug is the readable part of a URL: in /posts/creme-brulee, the slug is creme-brulee. It’s made from another column (usually the title): lower case, accents removed, words joined with dashes.

In Strutvane you declare the slug once in the migration, and the ORM fills it in every time a row is created and keeps it unique.

database/migrations/2026_11_14_093000_create_posts_table.ts
import { migration } from '@strutvane/framework/schema'
export default migration({
up(schema) {
schema.create('posts', (t) => {
t.id()
t.string('title', 200)
t.slug('slug').from('title')
t.timestamps()
})
},
down(schema) {
schema.dropIfExists('posts')
},
})

t.slug('slug') creates a unique text column called slug (255 characters unless you pass a length: t.slug('slug', 120)), and .from('title') says where its value comes from. Then:

  1. Run node strut migrate. The slug column and its unique index (posts_slug_unique) are created.
  2. Leave the model as it is: it needs nothing extra.
  3. Create rows without a slug; the ORM fills it in.
const post = await Post.create({ title: 'Crème Brûlée: 100% Better!' })
console.log(post.slug)

What you’ll see:

creme-brulee-100-better
  1. Accents are removed (é → e) and everything is lower-cased.
  2. Every run of characters that isn’t a letter or digit becomes one -.
  3. Dashes at the start and end are trimmed.
  4. It’s shortened to fit the column, leaving room for a suffix.
  5. If nothing is left (a title made only of symbols, or in a script without Latin letters), the slug is item.
Title Slug
Hello world hello-world
Crème Brûlée — 100% better creme-brulee-100-better
a_b a-b
!!! item
const first = await Post.create({ title: 'Launch' })
const second = await Post.create({ title: 'Launch' })
console.log(first.slug, second.slug)

What you’ll see:

launch launch-2

A third post titled “Launch” gets launch-3, and so on: Strutvane takes the next free number, so the suffix is friendly and predictable.

Behind the scenes:

  • Characters like % and _ in titles are plain characters: looking for taken slugs never treats them as wildcards, so a_b and axb don’t block each other.
  • Two requests at the same moment may pick the same slug. The database’s unique index refuses the second one, and Strutvane retries it with the next number. Inside a transaction, the retry uses a savepoint, so your surrounding transaction survives.
  • Soft-deleted rows keep their slug, so restoring them never clashes (a new “Launch” next to a deleted one gets launch-2).

On a tenant table (one with a tenant_id column, see Tenancy), slugs are unique within each tenant. Another team’s slugs are invisible and never change yours:

const a = await runWithTenant(teamA, () => Project.create({ name: 'Launch' }))
const b = await runWithTenant(teamB, () => Project.create({ name: 'Launch' }))
console.log(a.slug, b.slug)
// → launch launch (each team gets its own "launch")

When tenancy is on, t.slug() creates the unique index on (tenant_id, slug) instead of (slug), so the database agrees that two teams may both have launch. The ORM looks for taken slugs, and counts suffixes, only inside the active tenant: another team’s launch never makes yours launch-2.

If you set a slug, it’s kept as you wrote it; only empty slugs are generated:

const post = Post.make()
post.fill({ title: 'Our 2027 roadmap' })
post.slug = 'roadmap' // your own code: kept as is
await post.save()
console.log(post.slug) // → 'roadmap'

To let users type a slug in a form, list slug in fillable and validate its format in your form request (lower-case letters, digits and single dashes).

The slug is set when the row is created and doesn’t follow later title changes:

post.title = 'Our 2028 roadmap'
await post.save()
console.log(post.slug) // → still 'roadmap'

Shared links, bookmarks and search results keep working. Change the slug on purpose by assigning a new value.

const post = await Post.query().where('slug', 'creme-brulee-100-better').firstOrFail()

In routes, {post:slug} does this for you and answers 404 when nothing matches (see Routing).

t.string('title').from('name') // compile error: only slugs have .from()

Fix: declare the column with t.slug('slug').from('title').

Why: launch-3 doesn’t mean “the third launch”: numbers are taken by deleted rows too, and a renamed post keeps its old slug.

Fix: don’t parse suffixes. If you need a stable, readable name, set the slug yourself.

The slug didn’t change when I edited the title

Section titled “The slug didn’t change when I edited the title”

Why: slugs are stable on purpose, so links keep working.

Fix: assign the new slug yourself (post.slug = 'new-name'), and expect old links to break.

409 Conflict

Why: a slug you set yourself is kept as is, so if it’s already taken the unique index refuses it, and the generated API answers 409.

Fix: check first with Post.query().where('slug', value).exists(), or let Strutvane generate the slug.