Repository files navigation

Use Lucid models to create URL-safe unique slugs and persist them in the database.

Generating slugs is easy, but keeping them unique is hard. This package abstracts the hard parts and gives you a simple API to create and persist unique slugs to the database.

Lucid slugify exports the@slugify decorator, which you can use on the model fields to mark them as slugs and define the source fields from which the slug should be generated. Under the hood, the decorator registersbeforeCreate andbeforeUpdate hooks to compute the slug and persist it to the database.

In the following example, we mark theslug field as the slug and compute its value using thetitle field. We also use thedbIncrement strategy to keep slugs unique.

import{DateTime}from'luxon'import{BaseModel,column}from'@adonisjs/lucid/orm'import{slugify}from'@adonisjs/lucid-slugify'exportdefaultclassPostextendsBaseModel{  @column({isPrimary:true})declareid:number  @column()declaretitle:string  @column()  @slugify({strategy:'dbIncrement',fields:['title'],})declareslug:string}

You can install the@adonisjs/lucid-slugify package from the npm packages registry. Ensure your application uses@adonisjs/core@6 and@adonisjs/lucid@21.

npm i @adonisjs/lucid-slugify

yarn add @adonisjs/lucid-slugify

pnpm add @adonisjs/lucid-slugify

Once done, you can mark a field as a slug using the@slugify decorator. Make sure to specify the source field(s) from which the slug should be generated.

import{DateTime}from'luxon'import{BaseModel,column}from'@adonisjs/lucid/orm'// 👇 Import decoratorimport{slugify}from'@adonisjs/lucid-slugify'exportdefaultclassPostextendsBaseModel{  @column({isPrimary:true})declareid:number  @column()declaretitle:string  @column()// 👇 Use it on a column  @slugify({fields:['title'],})declareslug:string}

In the previous example, if two posts are created with the sametitle, they will have the sameslug value.

This won't be a problem if you are the only author of your blog since you can always rename titles or might never write two articles with the same title.

However, if it's a community blog or forum, the chances of creating two or more posts with the same title are quite high.

You can use one of the following strategies to prevent duplicate slugs even when the titles are the same.

ThedbIncrement strategy performs a select query to find similar slugs and appends a counter when a duplicate slug is found. Given you have a database table with the following slugs:

• Creating a post withslug=hello-world will result inhello-world-6.
• Similarly, creating a post withslug=introduction-to-social-auth will result inintroduction-to-social-auth-5.

+----+-----------------------------+-------------------------------+| id | title                       | slug                          |+----+-----------------------------+-------------------------------+| 1  | Hello world                 | hello-world                   || 2  | Hello world                 | hello-world-5                 || 3  | Hello world                 | hello10world                  || 4  | Hello world                 | hello-10-world                || 5  | Introduction to social auth | introduction-to-social-auth   || 6  | Introduction to social auth | introduction-to-social-auth-4 || 7  | Hello world                 | hello-world-2                 || 8  | Hello world fanny           | hello-world-fanny             || 9  | Hello world                 | post-hello-world              || 10 | Hello world                 | post-11am-hello-world11       || 11 | Hello world                 | post-11am-hello-world         || 12 | Introduction to social auth | introdUction-to-Social-auTH-1 |+----+-----------------------------+-------------------------------+

TheshortId strategy appends a10-digit short id to the slug to make it unique. This strategy does not perform any additional database queries.

exportdefaultclassPostextendsBaseModel{  @column({isPrimary:true})declareid:number  @column()declaretitle:string  @column()  @slugify({strategy:'shortId',fields:['title'],})declareslug:string}

+----+-------------+------------------------+| id | title       | slug                   |+----+-------------+------------------------+| 1  | Hello world | hello-world-yRPZZIWGgC |+----+-------------+------------------------+

By default, slugs are not updated when you update a model instance, and this is how it should be when slugs are used to look up a record, as changing a slug will result in a broken URL.

However, if slugs are not primarily used to look up records, you may want to update them.

You can enable updates by using theallowUpdates flag.

exportdefaultclassPostextendsBaseModel{  @column({isPrimary:true})declareid:number  @column()declaretitle:string  @column()  @slugify({strategy:'dbIncrement',fields:['title'],allowUpdates:true,// 👈})declareslug:string}

Theslugify decorator does not generate slugs when the value of one or more source fields isundefined ornull.

Following is the list of available options accepted by the@slugify decorator.

Custom strategies can be used if you want to handle the uniqueness of slugs yourself. A strategy must implement theSlugifyStrategyContract.

import{SlugifyStrategyContract}from'@adonisjs/lucid-slugify/types'exportclassMyCustomStrategyimplementsSlugifyStrategyContract{maxLengthBuffer:number=0asyncmakeSlugUnique(modelInstance:LucidRow,field:string,value:string):string{}}

ThemakeSlugUnique method receives the following arguments.

• modelInstance: Reference to the model instance that will be persisted in the database
• field: The name of the field for which the unique slug will be created.
• value: The base value to convert to a unique value.

Once you have created the strategy, you can use it with the@slugify decorator, as shown in the following example.

exportdefaultclassPostextendsBaseModel{  @column({isPrimary:true})declareid:number  @column()declaretitle:string  @column()  @slugify({strategy:()=>{returnnewMyCustomStrategy()},fields:['title'],})declareslug:string}

The default implementation used by Lucid slugify for creating slugs works great with English words. However, if you are using Non-Latin alphabets, replace the implementation for creating slugs with a custom one.

You can override the staticslugify method on theSlugifier class. The following code has to be executed only once.

import{Slugifier}from'@adonisjs/lucid-slugify'/** * Make sure to install the "transliteration" package */import{slugify}from'transliteration'Slugifier.slugify=function(value,options){returnslugify(value,{separator:options.separator,lowercase:options.lower,})}

One of the primary goals of AdonisJS is to have a vibrant community of users and contributors who believe in the principles of the framework.

We encourage you to read thecontribution guide before contributing to the framework.

To ensure that the AdonisJS community is welcoming to all, please review and abide by theCode of Conduct.

AdonisJS Lucid slugify is open-sourced software licensed under theMIT license.