DEV Community: Karl

Building a ToDo app with SwiftUI and Cosmic

Karl — Mon, 09 Oct 2023 19:09:42 +0000

Introduction

In this article, we're going to dive deep into a particularly powerful combination of technologies, SwiftUI and the Cosmic CMS, to build a cross-platform ToDo list app.

SwiftUI, a brainchild of Apple since 2019, is an innovative and intuitive UI toolkit that lets developers write UIs from one platform and share the code across all platforms. It's powering a new age of app development with its simplicity and efficiency in design.

But what's a great UI if we can't manage and deliver the content seamlessly? That's where our next tool, the Cosmic CMS, steps in. Cosmic, known as a headless CMS (content management system), enables us to manage content across various platforms with ease.

The task at hand is a cross-platform ToDo list app, a fundamental tool for productivity that helps us keep track of what needs to be done. Throughout this journey, we will explore the key features and benefits of a ToDo list app, such as managing tasks, organizing work, and improving productivity. It's an excellent way to understand CRUD (Create, Read, Update, Delete) operations and appreciate how SwiftUI and Cosmic can power such an application.

This unique blend of SwiftUI's cross-platform capabilities and Cosmic's efficient content management is going to provide us with an efficient and effective way to build a truly robust ToDo list app. So buckle up and let's enjoy the ride together!

Prerequisites

Before we dive into creating our application, it's crucial to have some necessary tools installed and configurations in place. Here are the steps you'll need to follow:

Installation Requirements and Setups

Xcode:

Xcode is an Integrated Development Environment (IDE) for writing, compiling, and debugging Swift code. You can download it directly from the Mac App Store. Make sure you have the most recent version installed for optimal performance and the latest features.
iOS SDK:

The iOS SDK (Software Development Kit) comes bundled with Xcode and enables developers to develop, test, and debug apps for iOS. Ensure the bundled iOS SDK is updated within Xcode's preferences settings.
Swift:

Swift is a robust and intuitive programming language created by Apple for iOS development. By installing the latest version of Xcode, you should inherently have the most recent stable version of Swift.
Cosmic SDK Swift:
The Cosmic SDK for Swift is a simple and elegant way to manage CRUD operations from your Swift or SwiftUI app.

Setting Up a New Cosmic CMS Account and Creating a New Project

Cosmic is the CMS that we'll use for data storage and management of our ToDo list app. Here are the steps to setup a new account:

Go to the Cosmic official website.
Click on the Sign Up button.
You can sign up with your GitHub, Google account, or manually by entering your details.
Upon signing up and logging in, create an empty project and Bucket (our 'data container').
Save the Bucket slug and API read/write key found in Bucket > Settings > API keys.

Now you're set up and ready to start building the ToDo list app!

Overview of SwiftUI

SwiftUI is a modern, cross-platform, declarative UI framework from Apple introduced in 2019. It is used for developing UIs for Apple's platforms – iOS, iPadOS, macOS, watchOS and tvOS. SwiftUI uses Swift language features like generics and type inference to ensure your UI works effectively. Here are some highlighted features:

Declarative Syntax: SwiftUI uses a declarative syntax, which means you just need to state what you want in the UI, and SwiftUI ensures your interface is in that state.
Design Tools: SwiftUI was built with a reciprocal relationship between code and design. It provides a live preview of the UI which updates as the code is changed. This powerful feature allows developers to see real-time changes while crafting their user interface.
Cross-platform: With SwiftUI, you're able to develop once and deploy on all Apple platforms.
Accessibility: SwiftUI comes with built-in accessibility features like voice-over, larger type, and contrast ratio. It carries out the heavy lifting allowing developers to create accessible apps without too much boilerplate.

In our task of creating a ToDo list app, SwiftUI will be handling all the UI aspects, making the design of our app more streamlined and intuitive.

Cosmic CMS

Cosmic is a cloud-based, Content Management System (CMS) that enables developers to manage and maintain content for their applications more efficiently. It allows you to create and manage the content for your application in a simple and intuitive way.

RESTful API: Cosmic provides a RESTful API allowing for easy integration with any web or mobile applications. The Cosmic SDK for Swift abstracts the REST API to manage the CRUD operations for our app, this is what we’ll be using for our app.

For our ToDo list app, we will be using Cosmic as the backend to handle all CRUD operations where our data will be stored and managed.

Building The ToDo List App

Setting Up Xcode

Start by building out a basic Xcode app project.

Once you’re done, you should have a simple ‘Hello, world!’ View. You may find that it defaults to macOS as we picked a Multiplatform app project. So you can just pick an iPhone target from the Targets list.

Integrating Cosmic

So firstly, we’re going to set up Cosmic by putting together our content model. This model is what we’ll also map to inside our SwiftUI project when we move over to there. I like to set up my model in Cosmic first so I can pre-fill with some placeholder data to help with response testing and scaffolding our UI.

During your initial setup, you’ll be navigated to create your first content type, stick with the ‘Multiple’ option as we’ll want to have multiple ToDos stored. Call it whatever you want, but ToDo is probably safest.

Our basic structure will be the following:

|— title
    [Metadata]
    |— is_completed
    |— due_date
    |— priority

The title of each object will be what we fill in when we create a new ToDo item, we’ll then have an option to mark it as completed or not (which will default to not, or false), set a due date, and finally a priority (low, medium or high).

This gives us lots of nice things we can do in our UI to help with sorting and styling.

Let’s create a couple of example todos to populate a little data.

We can even view our ToDo list in the Cosmic dashboard, almost as we will in our app

Fetching our data

We know we’ll have multiple todo items eventually, and therefore we’ll need to loop over them and present a list. Thankfully, the Cosmic SDK for Swift and SwiftUI is already set up in a way to handle this for us.

Now, we can write our API call to fetch our data.

Note: I’ve put my specific Cosmic credentials inside a ‘Secrets’ file so’s not to expose them during this tutorial, but note this is not a safe way to store them and shouldn’t be committed to GitHub.

Firstly let's start by creating a new ToDoViewModel.swift file. Pick a standard Swift type as we don't need access to SwiftUI here.

Now we need to add the SDK. Start by visiting the File menu and select 'Add package dependencies..."

Then, in the window, paste in the GitHub url to the search bar.

https://github.com/cosmicjs/CosmicSDKSwift

Once added, we just need to import it in the files we're working in. In this case, we should include it at the top of our file.

import CosmicSDK

Once we've done this, create a class for our model and make it Observable.

class ToDoViewModel: ObservableObject {
    private let BUCKET = CONST_BUCKET
    private let READ_KEY = CONST_READ_KEY
    private let WRITE_KEY = CONST_WRITE_KEY
    private let TYPE = CONST_TYPE

We're also going to declare some new local constants that pull from our secrets. This is just to keep things simpler and file private.

We can then initiate each of our global secrets directly within the Cosmic createBucketClient method. This is because we need to initiate the bucket client before our variables are available to the app.

private let cosmic = CosmicSDKSwift(
    .createBucketClient(
        bucketSlug: CONST_BUCKET,
        readKey: CONST_READ_KEY,
        writeKey: CONST_WRITE_KEY
    )
)

We then declare two published variables, this means that our app listens to changes from these as part of their observability

The first is our array of Objects which we remap to a simple items variable
The second is an error variable, this is so we can publish and capture any View Model errors provided by the SDK

@Published var items: [Object] = []
@Published var error: ViewModelError?

enum ViewModelError: Error {
    case decodingError(Error)
    case cosmicError(Error)
}

Inside of our fetchData() function, we use the find() method to get our data and pass it to the items array

func fetchData() {
    cosmic.find(type: TYPE) { results in
        switch results {
        case .success(let cosmicSDKResult):
            DispatchQueue.main.async {
                self.items = cosmicSDKResult.objects
            }
        case .failure(let error):
            print(error)
        }
    }
}

Note, you should write proper error handling, but I know we’re safe so I’ve left it simple

// ToDoViewModel.swift

import Foundation
import CosmicSDK

class ToDoViewModel: ObservableObject {
    private let BUCKET = CONST_BUCKET
    private let READ_KEY = CONST_READ_KEY
    private let WRITE_KEY = CONST_WRITE_KEY
    private let TYPE = CONST_TYPE

    private let cosmic = CosmicSDKSwift(
        .createBucketClient(
            bucketSlug: CONST_BUCKET,
            readKey: CONST_READ_KEY,
            writeKey: CONST_WRITE_KEY
        )
    )

    @Published var items: [Object] = []
    @Published var error: ViewModelError?

    enum ViewModelError: Error {
        case decodingError(Error)
        case cosmicError(Error)
    }

    func fetchData() {
        cosmic.find(type: TYPE) { results in
            switch results {
            case .success(let cosmicSDKResult):
                DispatchQueue.main.async {
                    self.items = cosmicSDKResult.objects
                }
            case .failure(let error):
                print(error)
            }
        }
    }
}

In order to decode our data correctly, we need to extend the SDK's provided Object to include the specific metadata keys to make them easier to use in our code later. Whilst this is an optional step, it helps to make the output a lot easier to work with.

Inside your ToDoViewModel file, at the very bottom, add the following extension. All this does is tell our code that we can expect specific optional metadata to be returned by the API, and we then map that to new variables that are easier to understand and use.

// Model
extension Object {
    var metadata_due_date: String? {
        return self.metadata?["due_date"]?.value as? String
    }
    var metadata_priority: String? {
        return self.metadata?["priority"]?.value as? String
    }

    var metadata_is_completed: Bool? {
        return self.metadata?["is_completed"]?.value as? Bool
    }   
}

Seeing it in our App

Let's head over to our ContentView.swift file and make some changes. First start by deleting all the boilerplate code and add the below code in.

We need to declare a @StateObject as this view will be our main source of viewing and updating our data
Once we have this, we can loop through our data inside a List
1. Once in there, we can actually iterate over these objects and get to the data we want
2. For now, we’ll just get the title of each todo

// ContentView.swift

import SwiftUI

struct ContentView: View {
    @StateObject var viewModel = ToDoViewModel()

    var body: some View {
        VStack {
            List(viewModel.items, id: \.id) { todo in
                Text(todo.title)
            }
        }
        .padding()
        .onAppear {
            viewModel.fetchData()
        }
    }
}

#Preview {
    ContentView()
}

If you build and run this, you should see the following. It doesn’t look terrible but it’s not great either. Also, we’re yet to have proper CRUD functionality, currently we simply have Read.

Notice that the order reflects what you see in Cosmic. Try re-ording your items and then build and run the app again, it should update to match!

Designing the UI with SwiftUI

Right, now it’s time to add some more things to the UI and make it look a little better. We’re not going to spend forever obsessing over the look, and we’re going to prioritise using SwiftUIs native components.

One thing we do need to do though, is to write a couple of helper functions. These allow us to map over our priority string and return two things:

A replacement for the priority word with an exclamation point
A color tint to help with glanceability

// ContentView.swift

func replaceTextWithValue(priority: String) -> String {
        switch priority {
        case "Low":
            return "!"
        case "Medium":
            return "!!"
        case "High":
            return "!!!"
        default:
            return "?"
        }
    }

    func determineColor(priority: String) -> Color {
        switch priority {
        case "Low":
            return Color.yellow
        case "Medium":
            return Color.orange
        case "High":
            return Color.red
        default:
            return Color.gray
        }
    }

And here’s our fully updated ContentView code

// ContentView.swift

import SwiftUI

struct ContentView: View {
    @StateObject var viewModel = ToDoViewModel()

    var body: some View {
        NavigationStack {
            VStack {
                List(viewModel.items, id: \.id) { todo in
                    VStack {
                        HStack {
                            Text(todo.title)
                            Spacer()
                            Image(systemName: "checkmark.circle")
                                .foregroundStyle(.secondary)
                        }
                        HStack {
                            Text(todo.metadata_due_date)
                                .font(.caption)
                                .foregroundStyle(.secondary)
                            Spacer()
                            Text(replaceTextWithValue(priority: todo.metadata_priority))
                                .fontWeight(.black)
                                .foregroundStyle(determineColor(priority: todo.metadata_priority))
                        }
                    }
                }
            }
            .navigationTitle("Cosmic ToDos")
            .onAppear {
                viewModel.fetchData()
            }
        }
    }

    func replaceTextWithValue(priority: String) -> String {
        switch priority {
        case "Low":
            return "!"
        case "Medium":
            return "!!"
        case "High":
            return "!!!"
        default:
            return "?"
        }
    }

    func determineColor(priority: String) -> Color {
        switch priority {
        case "Low":
            return Color.yellow
        case "Medium":
            return Color.orange
        case "High":
            return Color.red
        default:
            return Color.gray
        }
    }

}


#Preview {
    ContentView()
}

CRUD Operations With Cosmic

Cool, so now we’ve got that in place, we can think about implementing more of the CRUD operations. Let’s start with creating a new todo.

Create Operation

At the top of our file, we’ll first need to declare a new state for showing a sheet that’ll let us add a new todo

Insert @State var showAddNewSheet = false

We can then use this to toggle whether we show a sheet or not by adding the sheet modifier and binding it to our variable.

.sheet(isPresented: $showAddNewSheet) {…}

Create a new SwiftUI file called AddNewTodoView

In this view we’ll observe our StateObject by calling an @ObservedObject which we bind to a new variable.

@ObservedObject var viewModel: ToDoViewModel

In this new file we’ll initialise three variables to hold the title, due date and priority for us. I won’t go into lots of detail on how this all works, but it’s a basic form that allows someone to add the relevant elements we need to make our Create submission work.

// AddNewTodoView.swift

struct AddNewTodoView: View {
    @ObservedObject var viewModel: ToDoViewModel
    @Environment(\.dismiss) private var dismiss

    @State private var todoTitle: String = ""
    @State private var todoDueDate: Date = Date()
    @State private var todoDueDateString: String = ""

    enum Priority: String, CaseIterable, Identifiable {
        case low, medium, high
        var id: Self { self }
    }

    @State private var selectedToDo: Priority = .low

#if os(iOS)
    let update = UINotificationFeedbackGenerator()
#endif

    var body: some View {
        NavigationStack {
            Form {
                TextField("Enter a title", text: $todoTitle, axis: .vertical)
                DatePicker("Pick a date", selection: $todoDueDate, displayedComponents: .date)
                Picker("", selection: $todoPriority, content: {
                    ForEach(Priority.allCases) { priority in
                        Text(priority.rawValue.capitalized)
                    }
                })
                .pickerStyle(.segmented)
            }
            .navigationBarTitle("Add new ToDo")
            .navigationBarTitleDisplayMode(.inline)
            .toolbar {
                ToolbarItem(placement: .confirmationAction) {
                    Button {
                        update.notificationOccurred(.success)
                        self.dismiss()
                        DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
                            self.viewModel.createToDo()
                        }
                    } label: {
                        Text("Add")
                            .bold()
                    }
                }
                ToolbarItem(placement: .cancellationAction) {
                    Button {
                        self.dismiss()
                    } label: {
                        Text("Close")
                    }
                }
            }
            .onAppear {
                let dateFormatter = DateFormatter()
                dateFormatter.dateFormat = "YYYY-MM-dd"
                dateFormatter.locale = Locale.init(identifier: "en_GB")
                todoDueDateString = dateFormatter.string(from: todoDueDate)
            }
        }
    }
}

So now, when you press the plus button, you should see a nice little form.

Submitting our data

Now, in order to actually submit our data, we need to make another API call to Cosmic, but this time we’re inserting a new object.

We’ll start by creating a new function in our ToDoViewModel which expects to receive the title, due date and priority from the source where it’s called. We can now rely on another SDK method for insertOne() which just requires the type and title but can take optional parameters too. For our case, we'll rely on the optional metadata.

// ToDoViewModel.swift

func createToDo(title: String, due_date: String, priority: String) {
    cosmic.insertOne(type: TYPE, title: title, metadata: ["due_date": due_date, "priority": priority]) { results in
        switch results {
        case .success(_):
            print("Inserted \(title)")
            DispatchQueue.main.async {
                self.fetchData()
            }
        case .failure(let error):
            print(error)
        }
    }
}

The provided print statements are not required, but they just help to provide us with feedback whilst developing as we can review the console to see the creation worked.

Now in our AddNewTodoView we need to update the call to createToDo() to include the parameters we defined.

// AddNewToDoView.swift

DispatchQueue.main.asyncAfter(deadline: .now() + 0.2) {
    self.viewModel.createToDo(title: todoTitle, due_date: todoDueDateString, priority: selectedToDo.rawValue.capitalized)
}

Note that we have to do a little bit of clever stuff. Cosmic, expects the date to be a UTF8 formatted string, so we simply use a dateFormatter function to assign a String value from the Date value which gives us a string value back. For our Priority, we take the currently selected priority and access its raw value (which maps to what Cosmic is expecting) and capitalise it to ensure it matches our backend. If your key isn't capitalized, you can ignore this.

// AddNewToDoView.swift

.onAppear {
    let dateFormatter = DateFormatter()
    dateFormatter.dateFormat = "YYYY-MM-dd"
    dateFormatter.locale = Locale.init(identifier: "en_GB")
    todoDueDateString = dateFormatter.string(from: todoDueDate)
}

Now build and run your app again and things should work as expected and you should be able to add a new Todo! You’ll see it appear in Cosmic once you have, and see it in the UI too. This is because we re-fetch our data from the API on the main thread using a DispatchQueue if the creation was successful.

DispatchQueue.main.async {
    self.fetchData()
}

UI Cleanup

Let’s improve our date formatting on our todos to be a little more readable. I’ve written a small helper function that does this for us. Create a new file called Helpers.swift and add this in there.

// Helpers.swift

import SwiftUI

func parseDate(from dateString: String) -> String? {
    let dateFormatter = ISO8601DateFormatter()
    dateFormatter.formatOptions = [.withFullDate]
    if let date = dateFormatter.date(from: dateString) {
        let outputFormatter = DateFormatter()
        outputFormatter.dateFormat = "dd MMM yyyy"
        return outputFormatter.string(from: date)
    } else {
        return nil
    }
}

One thing I love about SwiftUI is that you don’t have to import files, Xcode is smart enough to see you’ve used it, and so long as it exists somewhere in your project, it auto imports it. Neat!

To use this, we simply call it inside the Text() element and access the description property.

// ContentView.swift

Text(parseDate(from: todo.metadata.due_date)?.description ?? "Invalid Date")
    .font(.caption)
    .foregroundStyle(.secondary)

That looks better!

We’ll also extract our TodoCell into its own component to make things cleaner on our ContentView.

First, move the two functions in ContentView that help parse our Priority information into your Helpers.swift file. Now they’re globally accessible.

Then, copy your individual todo code into a newly created ToDoCell.swift SwiftUI View file.

// ToDoCell.swift

import SwiftUI

struct ToDoCell: View {    
    @State var title: String = ""
    @State var date: String = ""
    @State var priority: String = ""

    var body: some View {
        VStack {
            HStack {
                Text(title)
                Spacer()
                Image(systemName: "checkmark.circle")
                    .foregroundStyle(.secondary)
            }
            HStack {
                Text(parseDate(from: date)?.description ?? "")
                        .font(.caption)
                        .foregroundStyle(.secondary)
                Spacer()
                Text(replaceTextWithValue(priority: priority))
                    .fontWeight(.black)
                    .foregroundStyle(determineColor(priority: priority))
            }
        }
    }
}

Update Operation

Now it’s time to make updates. Technically you can update anything here, but we’ll focus on simply completing the task and updating the Cosmic object so that it’s synced between uses.

For now, we’ll make the entire cell a touch target for completion, but, you may want to change this in the future if you want other functionality.

Add a new requirement to your ToDoCell.swift to get the current id of the item
Wrap the entire cell in a Button where the UI is the Button’s label property
Add a new function we’ll create for updating our ToDo in the Button’s action
Add a new variable for is_completed

// ToDoCell.swift

import SwiftUI

struct ToDoCell: View { 
    @State var id: String = ""
    @State var title: String = ""
    @State var date: String = ""
    @State var priority: String = ""
    @State var is_completed: Bool = false

    var body: some View {
        Button {
            viewModel.completeToDo(id: id)
        } label: {
            VStack {
                HStack {
                    Text(title)
                    Spacer()
                    Image(systemName: "checkmark.circle")
                        .foregroundStyle(.secondary)
                }
                HStack {
                    Text(parseDate(from: date)?.description ?? "")
                        .font(.caption)
                        .foregroundStyle(.secondary)
                    Spacer()
                    Text(replaceTextWithValue(priority: priority))
                        .fontWeight(.black)
                        .foregroundStyle(determineColor(priority: priority))
                }
            }
        }
        .buttonStyle(.plain)
    }
}

Now update your ContentView.swift to include this

// ContentView.swift

List(viewModel.items, id: \.id) { todo in
    ToDoCell(viewModel: viewModel, id: todo.id ?? "", title: todo.title, date: todo.metadata_due_date ?? "", priority: todo.metadata_priority ?? "", is_completed: todo.metadata_is_completed ?? false)
}

In order to make this work, we’ll add another function to our ToDoViewModel.swift file. This will allow us to update our is_completed switch to the new state. Now we'll be using the SDK's updateOne() method.

// ToDoViewModel.swift

func completeToDo(id: String, is_completed: Bool) {
    cosmic.updateOne(type: TYPE, id: id, metadata: ["is_completed": is_completed]) { results in
        switch results {
        case .success(_):
            print("Updated \(id)")
            DispatchQueue.main.async {
                self.fetchData()
            }
        case .failure(let error):
            print(error)
        }
    }
}

Now we have this, we’ll update our UI to toggle the state properly so we update our UI and our Cosmic data and keep them in sync. Here we use ternary operators to change the UI appearance of the checkmark based on the completion state.

// ToDoCell.swift

Button {
        is_completed.toggle()
        viewModel.completeToDo(id: id, is_completed: is_completed)
        } label: {
            VStack {
                HStack {
                    Text(title)
                    Spacer()
                    Image(systemName: is_completed ? "checkmark.circle.fill" : "checkmark.circle")
                        .foregroundStyle(is_completed ? .green : .secondary)
                }
                HStack {
                    Text(parseDate(from: date)?.description ?? "")
                        .font(.caption)
                        .foregroundStyle(.secondary)
                    Spacer()
                    Text(replaceTextWithValue(priority: priority))
                        .fontWeight(.black)
                        .foregroundStyle(determineColor(priority: priority))
                }
            }
        }
        .buttonStyle(.plain)

Delete Operation

Cool, so now we have Creation, Reading, and Updating working nicely. The final thing is to ensure we can delete any todo as well. Thankfully, because we used SwiftUI’s List API, we can easily utilise the inbuilt Delete method to remove an entry from the list and send that DELETE request to Cosmic.

Let’s create one last function in our ToDoViewModel.swift file. This time, it’ll be a deleteToDo() method.

You’ll see that our entire function is very similar to our update, we pass an id to the method and just tell it that we want to delete that id. In this case, we don’t need to send anything else along with it.

// ToDoViewModel.swift

func deleteToDo(id: String) {
    cosmic.deleteOne(type: TYPE, id: id) { results in
        switch results {
        case .success(_):
            print("Deleted \(id)")
            DispatchQueue.main.async {
                self.fetchData()
            }
        case .failure(let error):
            print(error)
        }
    }
}

Now we’ll add a swipeAction() to our cell to enable deletion.

Underneath our button style on the ToDoCell.swift, add a swipe action to include the delete functionality. Because we’re not dealing with Core Data or any other internal library, we can just use a simple button with a call to our delete method inside the action.

// ToDoCell.swift

.swipeActions(edge: .trailing) {
    Button(role: .destructive) {
        withAnimation {
            viewModel.deleteToDo(id: id)
        }
    } label: {
        Label("Delete", systemImage: "trash")
    }
}

Now when you swipe from right to left (or left to right, depending on your country), you’ll get the typical swipe to delete functionality and this will persist again across restarts as our data is always coming from Cosmic.

Building a Cross-Platform App

This won’t be perfect currently, and macOS will likely encounter errors as we have some specific functionality in there for iOS. But, you can build and run this on iPad without issue. It’s not fully optimised, and it’s not the ideal UI for the larger screen, but, it’s still usable. You can work to improve the iPad UI now that all the functionality is in here.

Conclusion

In this comprehensive guide, we've journeyed together through the process of creating a cross-platform ToDo list app using SwiftUI and Cosmic CMS.

We began with an overview of SwiftUI and Cosmic CMS, familiarizing ourselves with the main features and advantages of these modern technologies. We then proceeded into the nitty-gritty of app development, starting from installing and setting up prerequisites to designing the app UI and integrating Cosmic for seamless data management.

The core section of our journey revolved around executing CRUD operations with Cosmic, where we detailed creating, reading, updating, and deleting tasks. This practical experience showcased the versatility and usefulness of both SwiftUI and Cosmic.

The beauty and efficiency of utilizing SwiftUI and Cosmic have hopefully been thoroughly demonstrated throughout this development process. The ease with which we can create a visually appealing interface with SwiftUI and manage our content effectively with Cosmic makes this combination a highly recommended approach for any aspiring or experienced app developer.

Thanks to the fact we used Cosmic, you could even take this project further and develop a web interface using Next.js, for example, where changes would be reflected across your app too!

Next steps

I hope you found this guide instructive. Sign up to get started using Cosmic to power content for your websites and apps. Build your own mobile apps using the Cosmic Swift SDK.

Crafting a Dynamic Blog with Next.js 13 App Directory

Karl — Fri, 01 Sep 2023 08:08:44 +0000

This article was originally published on Cosmic

Introduction

Blogging is more than a hobby; for many, it's a profession or a way to establish thought leadership in a specific industry. Having a performant and SEO-friendly platform is essential. In this guide, we'll delve into building a blog template with the new features in Next.js 13 App Router.

Creating a Blog Template:

Explore the steps to design a responsive, efficient, and dynamic blog template. This tutorial emphasizes the advantages of leveraging Next.js 13, Cosmic, and a responsive design toolkit for a top-notch user and developer experience.

Key Tools Used:

Next.js 13: The first iteration of the renowned React framework to introduce the App Router, packed with enhanced features for full-stack development.
Cosmic: A headless CMS enables the independence of the data (content) layer and gives us the ability to quickly manage template content. In this case, our blog posts, authors and tags.
Tailwind CSS: A performant utility-first CSS framework that can be composed directly in your markup.
TypeScript: To ensure type safety across our project, if you prefer JavaScript you can rename all your tsx files as jsx (and ts to js) and resolve the errors.

Tutorial Breakdown

TL;DR

Install the template

View the live demo

View the code

Setting Up Next.js 13 App Directory

Initialize a new application with the latest Next.js features.
Install the necessary dependencies for the project.

pnpx create-next-app@latest nextjs-developer-portfolio
# or
yarn create next-app nextjs-developer-portfolio
# or
npx create-next-app@latest nextjs-developer-portfolio

Then install the dependencies.

cd nextjs-developer-portfolio
pnpm install
# or
cd nextjs-developer-portfolio
yarn
# or
cd nextjs-developer-portfolio
npm install

Let’s fire up our application! After running the command below, you can open up http://localhost:3000 in your browser.

pnpm run dev
# or
yarn dev
# or
npm run dev

Clone the template from GitHub (recommended)

We have a very simple project setup, which maps closely to our content model (more on this later).

|— app
  |— author
    |— [slug]
        page.tsx
  |— posts
    |— [slug]
        page.tsx
  layout.tsx
  page.tsx
|— components
|— fonts
|— lib

// the rest is typical Next.js structuring

Configuring Cosmic

To get started with integrating headless content, sign up for Cosmic with a free account and install the demo bucket for Simple Next.js Blog. After creating your account, create a new project. You will be prompted to start with either an empty project or a template. Select “Template”, then select the “Simple Next.js Blog” template that we are using in this tutorial to follow along with demo content.

Building the Content Model

As mentioned earlier, our content model maps very closely to our app structure. We have Object types for Author and Posts, and we have Object types for our Categories which are used by our PostCard component to render the badges in the UI.

If you haven’t installed the template, you’ll need to build a custom content model. To understand what data you’ll need for this, you’ll want to refer to the lib/types file which will show you the model structure as TypeScript types.

Note that in this case, id, slug and title are the default properties given to us when we make a new Object Type, and everything inside the metadata object is based on the specific model metafields we want to integrate.

// lib/types.ts

export interface GlobalData {
  metadata: {
    site_title: string;
    site_tag: string;
  };
}

export interface Post {
  id: string;
  slug: string;
  title: string;
  metadata: {
    published_date: string;
    content: string;
    hero?: {
      imgix_url?: string;
    };
    author?: {
      slug?: string;
      title?: string;
      metadata: {
        image?: {
          imgix_url?: string;
        };
      };
    };
    teaser: string;
    categories: {
      title: string;
    }[];
  };
}

export interface Author {
  id: string;
  slug: string;
  title: string;
  metadata: {
    image?: {
      imgix_url?: string;
    };
  };
}

The Content modeller allows you to drag and drop your metafields to build up your model or modify the existing model too.

Integrating the Cosmic SDK

To start working with Cosmic data, you’ll need to install the Cosmic SDK and initialize the Bucket client.

npm i @cosmicjs/sdk

Then, if you haven’t used our provided project code, create a file called cosmic.ts in a lib folder and make a call to create the bucket client like so.

// lib/cosmic.ts
import { createBucketClient } from '@cosmicjs/sdk';

const cosmic = createBucketClient({
  // @ts-ignore
  bucketSlug: process.env.NEXT_PUBLIC_COSMIC_BUCKET_SLUG ?? '',
  // @ts-ignore
  readKey: process.env.NEXT_PUBLIC_COSMIC_READ_KEY ?? '',
});
export default cosmic;

You can now import this wherever you need to fetch Cosmic data from your bucket. You can replace the environment variables with hard coded keys whilst you develop if you wish. Get your keys from Your Project > Bucket > API Access.

Setting Environment Variables

Alternatively, if you’re using Vercel (recommended) to host your project, you can add your BUCKET_SLUG and READ_KEY to your project and link it to Vercel using the Vercel CLI.

Fetching Blog Posts

To fetch blog posts, we can use a simple call to the Cosmic SDK and just get back exactly what we need.

// lib/cosmic.ts

export async function getAllPosts(): Promise<Post[]> {
  try {
    // Get all posts
    const data: any = await Promise.resolve(
      cosmic.objects
        .find({
          type: 'posts',
        })
        .props('id,type,slug,title,metadata,created_at')
        .depth(1)
    );
    const posts: Post[] = await data.objects;
    return Promise.resolve(posts);
  } catch (error) {
    console.log('Oof', error);
  }
  return Promise.resolve([]);
}

Here we use a Promise to declare an array of our Post type from the lib/types file and use the special objects.find() method to get the contents that matches our type of Posts. We then ask for specific props that we’ll need later when we render the UI. We have a reference to depth(1), this is because we only need a single layer of metadata. If we had nested object relationship, we’d need to declare a deeper depth.

Before the return statement, try adding console.log(posts) to make sure you’re getting a response back from Cosmic. That way you can be sure your environment variables are working correctly and you’ll see the data structure. You can check the Developer Tools drawer and the Node.js tab to see if it matches what you’ve got in there too.

Pro tip: This is a handy place to get a basic API request from too. Note we’ve added type safety in our implementation.

Markdown or Content Formatting

In this project, we’re using Rich Text to display our post contents, so we use Cosmic’s Rich Text Editor metafield. This means we do dangerously set our HTML in the UI. The Cosmic Rich Text editor offers handy shortcuts to make content creation a breeze.

It is highly recommended to use an XSS Sanitizer like DOMPurify to sanitize HTML and prevent XSS attacks. For Next.js projects, which prominently feature server-side rendering, Isomorphic DOMPurify is especially valuable. It offers a seamless sanitization process across both server and client, ensuring consistent HTML sanitization in environments like Next.js where a native server-side DOM isn't present.

If you’d rather not dangerously set your HTML, there are packages out there that wrap this functionality to provide other ways to present Rich Text.

You can also choose to convert this to Markdown and use our Markdown metafield instead if you prefer, just note you’ll need to install a markdown package to do so. The article Building React Components from headless CMS markdown is a great read about how a package like React Markdown parses markdown from a headless CMS, and explains how to render markdown in a Next.js application.

Designing the Blog Post Overview

So now we’re getting our Post data back, we need to display it on the page. Let’s do this in our main page.tsx file as that’s where we want our list of Posts to be shown by default. This is a blog after all.

First we’ll need a card to display our Posts. This relies on some sub components too, but let’s scaffold the main UI first.

Create a new PostCard.tsx file and start by exporting a PostCard component that expects to receive a post of type Post coming in.

// compoonents/PostCard.tsx

export default function PostCard({ post }: { post: Post }) {
  return (
   // The rest of our code will go here
  )
};

We know our code expects to get the following key parts: an image, a slug and a title. So let’s put these in.

// components/PostCard.tsx

export default function PostCard({ post }: { post: Post }) {
  return (
    {post.metadata.hero?.imgix_url && (
      <Link href={`/posts/${post.slug}`}>
        <Image width={2800} height={400} className='mb-5 h-[400px] w-full rounded-xl bg-no-repeat object-cover object-center transition-transform duration-200 ease-out hover:scale-[1.02]'
        src={`${post.metadata.hero?.imgix_url}?w=1400&auto=format`}
        priority alt={post.title}
        placeholder='blur'
        blurDataURL={`${post.metadata.hero?.imgix_url}?auto=format,compress&q=1&blur=500&w=2`} />
     </Link>
    )}
  )
};

Here, we’re guarding against not having an image url. Although adding a hero is not optional in our metafields, it is possible that one won’t get return if the network is too slow or the imgix server isn’t responding. This protects against this.

You’ll likely notice this line too:

// components/PostCard.tsx

src={`${post.metadata.hero?.imgix_url}?w=1400&auto=format`}

This uses imgix optimised URL parameters to provide us back with an image at the right size and format for our needs.

Now let’s add the title.

// components/PostCard.tsx

export default function PostCard({ post }: { post: Post }) {
  return (
    {post.metadata.hero?.imgix_url && (
      <Link href={`/posts/${post.slug}`}>
        <Image width={2800} height={400} className='mb-5 h-[400px] w-full rounded-xl bg-no-repeat object-cover object-center transition-transform duration-200 ease-out hover:scale-[1.02]'
          src={`${post.metadata.hero?.imgix_url}?w=1400&auto=format`}
          priority alt={post.title}
          placeholder='blur'
          blurDataURL={`${post.metadata.hero?.imgix_url}?auto=format,compress&q=1&blur=500&w=2`} />
        </Link>
    )}
    <h2 className='pb-3 text-xl font-semibold tracking-tight text-zinc-800 dark:text-zinc-200'>
      <Link href={`/posts/${post.slug}`}>{post.title}</Link>
    </h2>
  )
};

Great, next we want to include the Author’s avatar and an attribution for them. We’ll need to get these data based on the specific post we’re rendering. So let’s create components that we can pass our post into to get the right results.

Our Author avatar is nice and simple...

// components/AuthorAvatar.tsx

import Image from 'next/image';
import Link from 'next/link';
import { Post } from '../lib/types';

export default function AuthorAvatar({ post }: { post: Post }): JSX.Element {
  return (
      <Link href={`/author/${post.metadata.author?.slug}`}>
          <Image className='h-8 w-8 rounded-full'
          src={`${post.metadata.author?.metadata.image?.imgix_url}?w=100&auto=format`}
          width={32}
          height={32}
          alt={post.title}
          />
    </Link>
  );
}

And so is our attribution...

// components/AuthorAttribution.tsx

import { Post } from '../lib/types';
import helpers from '../helpers';

export default function AuthorAttribution({ post }: { post: Post }): JSX.Element {
  return (
    <div className='flex space-x-1'>
      <span>by</span>
      <a href={`/author/${post.metadata.author?.slug}`} className='font-medium text-green-600 dark:text-green-200'>
        {post.metadata.author?.title}
      </a>
      <span>on {helpers.stringToFriendlyDate(post.metadata.published_date)}</span>
    </div>
  );
}

So now in our PostCard.tsx component, we can import these and pass in the post along with the rest of the code required to make the card render our data.

// components/PostCard.tsx

import React from 'react';
import Link from 'next/link';
import Image from 'next/image';
import ArrowRight from './icons/ArrowRight';
import Tag from './Tag';
import { Post } from '../lib/types';
import AuthorAttribution from './AuthorAttribution';
import AuthorAvatar from './AuthorAvatar';

export default function PostCard({ post }: { post: Post }) {
    return (
    {post.metadata.hero?.imgix_url && (
        <Link href={`/posts/${post.slug}`}>
          <Image width={2800} height={400} className='mb-5 h-[400px] w-full rounded-xl bg-no-repeat object-cover object-center transition-transform duration-200 ease-out hover:scale-[1.02]'
          src={`${post.metadata.hero?.imgix_url}?w=1400&auto=format`}
          priority alt={post.title} placeholder='blur'
          blurDataURL={`${post.metadata.hero?.imgix_url}?auto=format,compress&q=1&blur=500&w=2`} />
        </Link>
    )}
    <h2 className='pb-3 text-xl font-semibold tracking-tight text-zinc-800 dark:text-zinc-200'>
      <Link href={`/posts/${post.slug}`}>{post.title}</Link>
    </h2>
    <div className='flex flex-col justify-between space-y-4 md:flex-row md:space-y-0'>
        <div className='flex items-center space-x-2 text-zinc-500 dark:text-zinc-400 md:space-y-0'>
          <AuthorAvatar post={post} />
          <AuthorAttribution post={post} />
        </div>
        <div className='flex select-none justify-start space-x-2 md:hidden md:justify-end'>
        {post.metadata.categories && post.metadata.categories.map((category) =>             <Tag key={category.title}>{category.title}</Tag>)}</div>
      </div>
      <div className='py-6 text-zinc-500 dark:text-zinc-300' dangerouslySetInnerHTML={{ __html: post.metadata.teaser ?? '' }} />
      <div className='flex items-center justify-between font-medium text-green-600 dark:text-green-200'>
        <Link href={`/posts/${post.slug}`}>
          <div className='flex items-center space-x-2'>
            <span>Read more</span>
            <ArrowRight className='h-4 w-4 text-inherit' />
          </div>
        </Link>
        <div className='hidden select-none justify-end space-x-2 md:flex '>{post.metadata.categories && post.metadata.categories.map((category) => <Tag key={category.title}>{category.title}</Tag>)}</div>
      </div>
    </div>
    )
};

Displaying the Blog Overview

Now we’ve got our card and we’ve got it rendering our data, we need to put this into our main page.tsx. Thanks to the new App Router structure with React Server Components, we don’t need to utilise special functions like getServerSideProps() to fetch our data. Instead, we can simply await our getAllPosts() function and return the data to the view.

// app/page.tsx

import React from 'react';
import PostCard from '../components/PostCard';
import { getAllPosts } from '../lib/cosmic';

export default async function Page(): Promise<JSX.Element> {
  const posts = await getAllPosts();

  return (
    // The rest of our code will go here
  )
}

So, to return our list of posts (if you’ve used the template, you already have 5 example posts, otherwise you’ll need to add some) we simply need to map over our returned array of data and pass it to our PostCard component to render.

// app/page.tsx

import React from 'react';
import PostCard from '../components/PostCard';
import { getAllPosts } from '../lib/cosmic';

export default async function Page(): Promise<JSX.Element> {
 const posts = await getAllPosts();

  return (
   <main className="mx-auto mt-4 w-full max-w-3xl flex-col space-y-16 px-4 lg:px-0">
     {!posts && "You must add at least one Post to your Bucket"}
     {posts &&
       posts.map((post) => {
         return (
           <div key={post.id}>
             <PostCard post={post} />
           </div>
         );
       })}
   </main>
 );
}

Generating Individual Blog Post Pages

So great, we’ve got a nice list of blog posts now… but we can’t see any of them when we click anything.

I won’t cover the entire code necessary to render the individual blog post (you can find that in the sample code, but I’ll cover a few important App Router elements we’ll need to consider.

First is the generateMetadata() function. This allows us to create dynamic metadata based on the given blog post that’s being viewed. This is important for good SEO and also when sharing via social platforms. You can go wild with this, generating dynamic OG images with custom titles and other data if you want.

In our case, we’re keeping it simple.

// app/posts/[slug]/page.tsx

export async function generateMetadata({ params }: { params: { slug: string } }) {
  const post = await getPost({ params });
  return {
    title: `${post.title} | Simple Next 13 Blog`,
  };
}

Here we simply return the current blog post’s title to the title property in our metadata object. This means the title in the browser tab/window, as well as when shared on social media, will match our current blog post.

One other useful element we have, which leverages the power of the Cosmic SDK, is the ability to show suggested posts that aren’t the current post you’re viewing.

In the UI, this looks like this (where SuggestedPostCard is very similar in structure to the typical PostCard, just with a simplified UI).

// app/posts/[slug]/page.tsx

<div className='flex flex-col space-x-0 space-y-4 md:flex-row md:space-x-4 md:space-y-0'>
   {suggestedPosts.slice(0, 2).map((post) => {
       return <SuggestedPostCard key={post.id} post={post} />;
   })}
</div>

The way we prevent getting the post we’re currently on, is by passing an extra property to our find() method. Here’s just the relevant fetch part of the code.

// lib/cosmic.ts

const data: any = await Promise.resolve(
  cosmic.objects
   .find({
     type: 'posts',
     slug: {
       $ne: params?.slug,
     },
   })
   .props(['id', 'type', 'slug', 'title', 'metadata', 'created_at'])
   .sort('random')
   .depth(1)
);

Notice that we say we want any where the slug is not equal to the params?.slug. To do this, we passed in the params to the function like so export async function getRelatedPosts({ params }: { params: { slug: string } }): Promise<Post[]>. This means that when we reference it in our page and pass the page params, the function knows to avoid that current slug.

The fetch that does this, looks like so:

// app/posts/[slug]/page.tsx

const suggestedPosts = await getRelatedPosts({ params });

Deployment

Now, if you’ve chosen to follow along exactly, there’ll be some missing pieces before you can actually deploy this project. Take a look at the sample code to see what you might need and make adjustments accordingly to get it up and running.

We host our example on Vercel, so as noted earlier, it’ll be easy to get set up if you’re using it. Otherwise, you can push this up to any other platform of choice such as Netlify.

Conclusion

By following this tutorial, you'll have a modern, dynamic, and efficient blog template powered by Next.js 13 App directory. Engage with the developer community, share your experiences, and always look for ways to improve and innovate. Your blog is not just a platform; it's an evolving entity that reflects your voice and expertise.

Ditching State for searchParams: The Future of Next 13

Karl — Fri, 18 Aug 2023 14:09:29 +0000

This article was originally posted on the Cosmic.js Blog.

Prerequisites

In order to get the most out of this article, you'll need a few things:

To be using Next.js 13 or later.
To be utilizing the new App Router project structure.
To be familiar with React's useState hook, and likely already be using it.
To be aware of the underlying fundamentals of client and server components in React 18 and Next 13.
To be using Cosmic as your CMS of choice (although these approaches will work for other data stores such as databases or other CMSs).

Getting started

In our case, we're going to migrate an existing client-side pagination to the server. But why would we want to do this?

Client-side pagination, in itself, isn't an issue. There's nothing wrong with holding your state in the browser DOM and updating it when things change or need to change. Fundamentally, this is how a lot of us have handled pagination in React projects in the past.

But with React Server Components (RSC), we're able to shift this logic over to the server. This means a few things:

We're shipping less client-side JavaScript which is great for page load times, and SEO.
We're able to store state in the URL params rather than in a state object, making these URL states shareable with others.
We keep all of our app logic on the server, so re-fetching data is a server-server interaction rather than client-server.

Let's look at a typical use case.

useState-powered Pagination

In our existing structure, we have two things. A call to Cosmic to fetch our data, and a state that handles knowing what page we're on.

Our Cosmic content

import { createBucketClient } from "@cosmicjs/sdk";

// Connect to your Bucket. Find the keys in Bucket > Settings > API keys
const cosmic = createBucketClient({
  bucketSlug: BUCKET_SLUG,
  readKey: BUCKET_READ_KEY
});

export async function getPosts(
  page?: number
): Promise<Post[]> {
  const data = await Promise.resolve(
    cosmic.objects
      .find({
        type: 'posts'
      })
      .props([
        'id,slug,title,metadata'
      ])
      .limit(9)
      .skip(((page ?? 1) - 1) * 9)
  );
  const posts: Post[] = await data.objects
  return posts
}

So just to break this down if you're less familiar with the Cosmic SDK, here we're making an async request to the Cosmic SDK which allows us to fetch our data. We're passing in a single param, which is our optional page param to get the current page number.

This page number gets passed to our find method's .skip(). When combined with limit(), skip() ensures that we can take the current page number in, remove 1, and then multiply by the limit number.

Let's break down this process:

Start with the current page number, for example, 1.
Subtract 1 from this number. In this case, 1 - 1 = 0.
Multiply the result (0) by our set limit, which is 9. This gives us 0 again.
We instruct our Cosmic data fetch to 'skip' by this result.

So, if we are on page one and use the 'skip' function, we will retrieve the first 9 posts. If we move to page 2, we take the number 2, subtract 1 to get 1, multiply by 9 to get 9, and then skip the first 9 posts. This will show us posts 10 through 18, effectively giving us "page 2".

Our State

So, this in theory works. But without any client-side control, we're just going to always see the first 8 posts forever. And that's not useful!

To handle this in our existing client-side State-powered world, we'll use useState from React.

We're going to keep things nice and simple.

const [page, setPage] = useState(1)

const previousPage = () => {
  setPage(page !== 1 ? page - 1 : 1)
}

const nextPage = (newPage: number) => {
  setPage(newPage)
}

Let's break this down now. We've got a simple state controller which holds an initial state of 1. We then have two simple functions which take in the current page value and then either remove 1 from the current page or add one.

For the previousPage function we have a little ternary guard that ensures we don't end up with negative page numbers.

So to get this into our page, we declare our fetch request like so, and pass in our current page from our state:

const posts = await getPosts(page)

And now, we can pass the pagination functions to a simple button to update our state and handle the pagination transitions.

Switching to searchParams

First thing's first, we need to lose the state. So let's delete our state declaration and remove the import dependency.

So now we don't hold state, where does our state live? Well, thanks to Next 13, it lives in the URL params.

To make this work, we'll request the searchParams in the main Posts page. [Note: you can find out more about searchParams in the Next.js 13 Docs]

export default async function Posts({ searchParams }) {
  // Your Posts content
};

Next, we'll need to create a little logic to validate the page received from our searchParams is a typeof string and then convert it to a number so the data fetch won't complain. This is all Type safety stuff, so if you're not using TypeScript, you can skip these bits (but I'd recommend you do use TypeScript!)

const page = typeof searchParams.page === "string" ? +searchParams.page : 1;

This is similar to how we declared our state and set a default value of 1. It's a little more verbose, but it ensures our params are type safe.

You'll notice that searchParams includes a .page property on it. This is because searchParams is a special type of parameter that has extra properties you can access. Thanks to it being a Next-specific parameter, Next has the type completions in place to make this obvious and accessible.

Pagination

Cool, so now that's done, we need to handle passing our pagination. We can remove our original function calls now too, we'll handle this logic in a special component. This is so we can move our client logic to the lowest possible level in our stack if we need to. In our case, we don't need that, but it's good practice in case you need to access the client at any point down the line.

Create a new component called Pagination and put it where you like to keep them. Either alongside your pages, or in a separate directory.

In there, we'll import Link from "next/link" to allow us to navigate. We're also going to need to pass in a couple of things, which is our posts and our page.

export const Pagination = ({
  posts,
  page,
}: {
  posts: Post[];
  page: number;
}) => {
  return (
    // Our page code
  )
};

So now let's handle that logic.

 return (
    <div className="mt-8 flex w-full justify-between">
      <Link
        className={
          page === 1 && "pointer-events-none opacity-50",
        }
        href={`?page=${page - 1}`}
      >
        Previous
      </Link>
      <Link
        className={
          page === posts.length && "pointer-events-none opacity-50",
        }
        href={`?page=${page + 1}`}
      >
        Next
      </Link>
    </div>
  );

Include whatever classes you want to for styles here, for now we'll keep it simple and just apply styles for remove pointer events and reducing the opacity if the page is either the initial page, or the final page. We've determined the final page by just measuring the length.

Now to get this working in our main page, we just need to import our new Pagination component and assign the required props for posts and page.

<Pagination posts={posts} page={page} />

And that's how simple it is.

Putting it altogether

Note: I've applied some default styles to a few things and assumed you have a specific Cosmic bucket in place with the data you need.

import { createBucketClient } from "@cosmicjs/sdk";

const cosmic = createBucketClient({
  bucketSlug: BUCKET_SLUG,
  readKey: BUCKET_READ_KEY
});

type Post = {
  title: string
  metadata: {
    subtitle: string
  }
}

export async function getPosts(
  page?: number
): Promise<Post[]> {
    const data = await Promise.resolve(
      cosmic.objects
        .find({
          type: 'posts'
        })
        .props([
          'id,slug,title,metadata'
        ])
        .limit(9)
        .skip(((page ?? 1) - 1) * 9)
    );

    const posts: Post[] = await data.objects
    return posts
}

export default async function Posts({ searchParams }) {
  const page = typeof searchParams.page === "string" ? +searchParams.page : 1;
  const posts = await getPosts(page);

  return (
    <div className="mx-auto w-full">
      <div className="flex w-full items-center justify-between">
        <header>Posts</header>
      </div>
      <div className="mt-8 grid grid-cols-1 gap-8 md:grid-cols-3 md:gap-16">
        {
         posts.map((post: Post, idx: number) => (
             <Link href={post.href}>
              <div className="group flex h-full flex-col justify-between space-y-2 rounded-xl transition-all ease-in-out ">
                <div className="flex h-full flex-col">
                  <div className="flex w-full items-start justify-between gap-2">
                    <header className="mr-2 block pb-2 text-lg font-medium leading-tight text-zinc-700 group-hover:underline group-hover:decoration-zinc-500 group-hover:decoration-2 group-hover:underline-offset-4 dark:text-zinc-200">
                      {post.title}
                    </header>
                    <ArrowRightIcon className="h-4 w-4 flex-shrink-0 text-zinc-500 dark:text-zinc-400" />
                  </div>
                  <span className="block pb-2 text-zinc-500 dark:text-zinc-400">
                    {post.subtitle}
                  </span>
                </div>
              </div>
            </Link>
           )
         )};
       </div>
      <Pagination posts={posts} page={page} />
    </div>
  );
}

Concluding things

So now you're able to pass all of your search logic into your URL parameters and not use any client-side JavaScript for it.

http://localhost:3000/?page=3

Try navigating to page 3, then copy the URL and paste it into an incognito window. It'll load up with the exact right data, and you'll be able to navigate from there back or forth. How cool is that!

For more information about how to use Cosmic in your application, visit our documentation
Want to get started with Cosmic? Create an account for free.

Design is Temporary

Karl — Thu, 27 Jul 2023 18:56:33 +0000

Product Design as artefact

We need to get comfortable with the idea that product design is a temporary measure to get us from nothing to solution.

I recently had some feedback on a design where I’d used a screenshot to mock a part that wasn’t being built as it helped describe the layout. The feedback I got was that the alignment on that screenshot wasn’t perfect. But it didn’t matter to the developer anyway, because it was pre-existing code that just provided value when understanding the context of what I had designed.

This is a small thing, and fixing that is trivial, but also unnecessary.

Throwing things away

Digital design as part of the product process is where ideas—usually from non-designer and from inside their head—first become real. So it’s natural for us to hold on to them as a permanent artefact that communicates that moment in time. But it’s just that—a moment in time.

To realistically keep a design in sync with reality, we’d have to carefully structure our file, maintain our layer names, and return back to it regularly to tend to the garden. This is counterintuitive and reduces effort well spent on new ideas and novel solution finding.

Thinking of design as throwaway helps to reduce friction and keep the eye on the prize—shipping something real. The closer we can stay together with engineering and develop in tandem, the better the overall outcomes. And Design Engineers can bridge this gap even better by understanding both sides and building fast prototypes in real code.

You’ve likely experienced that the most pertinent and frequent feedback comes when people are testing the real thing, so the closer (and earlier) you get to real the better the outcomes for everyone, especially your sanity.

Design is crucial

This doesn't mean that we should completely disregard the importance of design. In fact, it's quite the opposite. Design plays a crucial role in the success of a product. However, we need to shift our mindset from viewing design as a static, unchanging source of truth, to a temporary artefact that realises a product vision.

Design is a tool that helps us get to the end goal, which is a successful product. It's important to remember that the design is not the end goal itself. The design is a means to an end. Once the product is launched, the design will continue to evolve and change based on user feedback and market trends. This is why it's important to view design as a temporary measure. By doing so, we can focus on creating the best possible product and not get bogged down by the design process.

Furthermore, viewing design as temporary also allows for more experimentation and risk-taking. When we are not overly attached to a particular design, we are more willing to try out new ideas and take risks that could lead to a better product. This mindset also encourages collaboration and iteration, as we are more open to feedback and willing to make changes to improve the product.

Focusing on the end goal

Whilst design is an important part of the product development process, it's crucial to view it as a temporary measure rather than a permanent artefact. By doing so, we can reduce friction, focus on the end goal, and be more open to experimentation and collaboration. Ultimately, this mindset can lead to a better product and a more successful outcome.

So when someone asks “do you name your layers?”, say no and enjoy yourself. If you’re close with your engineers, they won’t read the layer names anyway because it really doesn’t matter that much (believe me, I used to do it).

The Design Engineer

Karl — Tue, 18 Jul 2023 18:08:41 +0000

The unicorn is dead, long live the unicorn

The role of a Design Engineer, formerly known as a Design Unicorn™, is still not fully understood by most organizations. About ten years ago, when Facebook, Google and all the other big Product orgs started shipping like crazy and defining our design landscape, the idea of a designer who could do engineering too was seen as the only choice.

These teams had already morphed a graphic designer into a UI designer and then merged this with UX designers into the famed Product Designer role we now see everywhere. So we’ve already merged a lot of skills, why then should we also tack on the ability to build things ready for production?

Well, because when a company recognizes the value of this, it can make a significant impact on the success of a project.

Should Designers Code™

The great debate of the late 2010’s. This did the rounds for too long to remember, and everyone had insanely strong opinions on both sides. In reality, some designers should code and some shouldn’t. And the level to which they contribute shipping code is also available on a sliding scale.

See, I’ve noticed across the web, that we get particularly fired up about what’s expected of a role at a general level. I know why, we wan’t to benchmark across the industry, ensure pay is equitable and fair, and make it easier to go from nothing to Product Designer. But, creating this segmentation of Design—or Engineering, depending on how you look at it—enables organisations to create an additional role that adds value in the middle.

Not all companies need it, not all teams will be able to make it work, and not all designers should code. But when the right org, with the right needs introduces the idea of Design Engineering, the product is vastly better in many ways.

The great free-ing up

By empowering the idea of the Design Engineer, we enable designers to ship their idea from concept to delivery. This gives greater ownership over an idea, and frees up an engineer to focus on other tasks that are potentially more critical or more technical.

A Design Engineer (DE) could have varying degrees of skill in either Design or Engineering, taking that strength forwards to empower the opposite team to do more. A strong DE who’s more designer brings the quality of the delivered engineering work up significantly, often upskilling engineers on important UX or UI principles. On the other hand, a strong DE who’s more engineer brings the technical limitations or knowledge of the APIs closer to design, better reducing unbuildable designs.

Building bridges

The Design Engineer acts as a bridge between the design and engineering teams, which often have the same end goal but different approaches to achieving it. By being the glue that aligns these teams, the Design Engineer can ensure that everyone is on the same page and working towards the same objective.

In organizations that truly understand the value of a Design Engineer, this role is not limited to a specific team or task. Instead, the Design Engineer is deployed to support design or engineering tasks as needed, depending on what requires the most attention at that moment. This flexibility allows the Design Engineer to be more effective in their role and to have a greater impact on the project's success.

Closing remarks

When searching for a similar blend, the merging of UX and UI again came to mind. Just as UX and UI are two sides of the same coin, design and engineering are two critical components of software development. The Design Engineer brings these two components together, ensuring that the end product is not only visually appealing but also functional and efficient.

In organizations that truly understand the value of a Design Engineer, this role is given the autonomy to see a project through from concept to delivery. This level of involvement allows the Design Engineer to have a greater impact on the quality of the software being developed. Importantly, the Design Engineer doesn’t replace the need for a Designer or an Engineer, they simply provide a hybrid skillset that makes things better for everyone.

You’ll often find that startups or organisations with less functional structuring are more open to these ideas. When you split requirements down by function, rather than objective, you care more deeply about what someone’s “role” is. When you focus on delivering objectives, you care more about the how and what, and less about who.

The role of a Design Engineer is critical to the success of any software development project, and in my opinion we will see it increase significantly in the next 5 years. Watch this space.

Creating a bookmarking utility with Raycast Extensions and Cosmic

Karl — Fri, 07 Jul 2023 09:17:44 +0000

Raycast and Cosmic

Prerequisites: Raycast Extensions only work on macOS, so if you’re on another device then sadly this tutorial isn’t worth your time.

The Cosmic Bookmarks Extension can be found and downloaded from the Raycast Store.

What is a Raycast extension?

Raycast Extensions allow you to complete tasks, create lists, browse media and improve your workflow. You can manage all of your Extensions through a set of built-in developer tools, and publish Extensions to the Raycast Store, and share with the world. Today we’ll get you on the path to doing just that (although you won’t be able to publish this exact Extension as it already exists on the store!).

Raycast Extensions use React but compile to native macOS code under the hood. This means you can write them using the web framework you know already, but still get all the benefits of native code.

What is Cosmic?

Cosmic is a headless CMS that is all about accelerating the development of content-driven applications. Cosmic offers expansive tools like a JavaScript SDK, allowing developers to easily get content into their applications. You can read the Cosmic Documentation to learn how access your content and extend the dashboard functionality.

How can Raycast and Cosmic be combined to create a website bookmarking utility?

Make sure you have Raycast installed and you’ve got a Cosmic Bucket ready (you can follow along using the Raycast Bookmarks template to have all the necessary Object Types set up, alongside some sample objects).

Step 1: Set up your Raycast extension

This step involves creating a new Raycast extension and setting up the necessary files and directories.

Firstly we’ll set up using the Raycast command bar flow.

Open the Create Extension command, name your extension "Hello World" and select the "Detail" template. Pick a parent folder in the Location field and press ⌘ ↵ to continue.

Now build the extension. Open your terminal, navigate to your extension directory and run npm install && npm run dev. Open Raycast, and you'll notice your extension at the top of the root search. Press ↵ to open it.

You can now remove the core code from this initial file and start with a clean slate.

Imports

We’ll need to import a few different things to get started. We’ll start with what’s required from the Raycast API. Raycast has very opinionated and strongly typed components and styles for use via their API. It’s imperative you use these as they map to native macOS code when Raycast renders them. But, for ease, you’ll be writing all of this in React.

Start by installing the additional required dependencies npm i @raycast/utils react, this ensures that we have access to all the things we need to write good, type-safe code.

import {
  Action,
  ActionPanel,
  Icon,
  List,
  getPreferenceValues,
  openExtensionPreferences,
  Toast,
  showToast,
} from "@raycast/api";
import { useFetch } from "@raycast/utils";
import React from "react";

Now that we’ve got these pieces in place, we’ll need to integrate with Cosmic.

Step 2: Integrate Cosmic

In this step, you will integrate Cosmic into your Raycast extension by adding fetch requests and configuring the CMS settings.

We’re going to leverage Raycast’s built in preference storage to manage holding the Bucket slug, and read key. This means we don’t need to create our own local store and we can rely on Apple’s built in keychain encryption.

Start by declaring your Preferences interface. This ensures we get type completion and helps us catch any errors.

interface Preferences {
  bucketSlug: string;
  readKey: string;
}

Next, to strengthen the type safety of our fetch requests later on, we’ll declare the interface types for our Objects List and our Singular Object. This again means that we’ll get autocompletion and catch typing errors. We can do this because we know what our model needs to look like ahead of time.

interface ObjectsList extends React.ComponentPropsWithoutRef<typeof List> {
  objects: [
    {
      id: string,
      type: string,
      title: string,
      slug: string,
      metadata?: {
        snippet: string,
        url: string,
        read: boolean,
      },
    }
  ];
}

interface SingularObject extends React.ComponentPropsWithoutRef<typeof List> {
  object: {
    id: string,
    type: string,
    slug: string,
    title: string,
    metadata: {
      published: string,
      snippet: string,
      url: string,
      read: boolean,
    },
  };
}

ObjectsList

This Interface is for our full list of Objects. Think of this like our Extension’s representation of the Objects Table in your dashboard. The difference here is that our List will provide preview data in the Raycast UI which comes from the SingularObject.

SingularObject

This is the equivalent of viewing the detail of a specific Object in the dashboard, only we’re rendering specific parts of the content in the frontend, much like if you were rendering it on your own website or app.

Adding your keys

Now that we’ve done this, we’ll want to actually input these values and use them in our extension. In Cosmic, go into your Dashboard and visit {project-name} > {bucket-name} > Settings > API access and get your Bucket Slug and Read Key.

Note, the keys in this example are fake and won’t work.

Step 3: Fetch your Bookmarks

Now let’s fetch these Bookmarks into our extension and see how it’s looking.

We need to start by declaring the default function expected by Raycast extensions, this is the Command() function. Think of this as your Root() function that Raycast expects so it can operate.

export default function Command() {
  const { bucketSlug, readKey } = getPreferenceValues<Preferences>();
    const uri = `https://api.cosmicjs.com/v3/buckets/${`bucketSlug`}/objects?{"type":"bookmarks"}&read_key=${`readKey`}&depth=1&props=slug,title`;

    const encoded = encodeURIComponent(uri);
    const { data, isLoading } = useFetch<ObjectsList>(encoded);


{/* The rest of our code */}

}

Here we’re using the getPreferencesValues() method to fetch the bucketSlug and readKey. To actually get these and ensure they’re stored safely, we need to modify the package.json file.

In our package.json we can include the following JSON to tell Raycast that we want to use the default Preferences view when the extension is first loaded (and provide a way to update these in Raycast’s Settings). The beauty here is that we’ve done almost zero work, but got a default interface from Raycast.

You can add this anywhere, but I’d recommend sitting it underneath devDependencies.


"preferences": [
    {
      "name": "bucketSlug",
      "title": "Cosmic Bucket Slug",
      "description": "Your Cosmic Bucket Slug",
      "type": "textfield",
      "defaultValue": "",
      "required": true
    },
    {
      "name": "readKey",
      "title": "Cosmic Read Key",
      "description": "Your Cosmic Read Key",
      "type": "password",
      "defaultValue": "",
      "required": true
    },
]

Step 4: Create our UI

Now we’ll actually render the bookmarks we’ve fetched.

Underneath our fetch constants, we’ll add this return statement, this pulls the data from our useFetch() hook and enables us to render a safe Objects List as the fetch request expects us to return an ObjectList with valid properties.

return (
  <>
    <List isLoading={isLoading} isShowingDetail>
      {data?.objects.map((object) => (
        <List.Item
          key={object.id}
          title={object.title}
          detail={
            <ObjectDetail id={object.id ?? ""} title={object.title ?? ""} />
          }
          actions={
            <Actions
              id={object.id ?? ""}
              title={object.title ?? ""}
              read={object.metadata?.read ?? false}
            />
          }
        />
      ))}
    </List>
  </>
);

As you’ll see, the code is very neat because we get to take advantage of the provided components from Raycast. No styling required, and no heavy lifting on our part. We render a <List> which has two properties we want to take advantage of; an isLoading prop which is just a boolean that ensures we present a loading UI in Raycast if the data is being fetched (and with a lot of bookmarks, this would be likely); and isShowingDetail which is another boolean that presents the secondary detail view for us without having to first click on an entry.

Our key and title props in the <List.Item> are the main object id and object title that each individual Cosmic object has. You’ll rarely see the id in the Cosmic interface as it’s only really exposed in the API, but know that each id is unique which is handy for our map().

We also have two special props, detail={} and actions={}, these two props provide a way for us to present what we want our detail view to be and what actions we want available via the ⌘+K shortcut.

Detail

For this, we’ll use a similar approach to our main ObjectsList but we’ll be rendering data on a per-Object level.


function ObjectDetail(props: { id: string; title: string }) {
  const { bucketSlug, readKey } = getPreferenceValues<Preferences>();

  const { data, isLoading } = useFetch<SingularObject>(
    `https://api.cosmicjs.com/v3/buckets/${bucketSlug}/objects/${props.id}?read_key=${readKey}&depth=1&props=`
  );

  if (!data?.object) {
    return null; // Return null when data is not available
  }

{/* The rest of our code */}

}

Again, we’re fetching the preferences we have stored in the main interface, this is so that we can pass them into our new useFetch() hook. In this case, we’re telling Raycast that we want our fetch to match the interface we defined for SingularObject for strong type safety and autocomplete (thanks Typescript!).

So now we can actually load our detail view and see what we’ve been looking for! Comment out the lines for now to enable it to render.


{/* actions={
  <Actions
    id={object.id ?? ""}
    title={object.title ?? ""}
    read={object.metadata?.read ?? false}
  />
} */}

In this detail view, we’re using a simple regex command that I wrote about here to trim the domains we show to just the core site name (often known as an eTLD+1 trim).


const regex = /.*https:\/\/www\.|http:\/\/www\.|https:\/\/|http:\/\/|\/.*$/gm;
  const trimmedURL = data?.object.metadata.url.replace(regex, "");

  return (
    data?.object && (
      <List.Item.Detail
        isLoading={isLoading}
        markdown={
          `## ${props.title}` +
          "\n\n" +
          `${data?.object.metadata?.snippet ?? ""}`
        }
        metadata={
          <List.Item.Detail.Metadata>
            <List.Item.Detail.Metadata.Label
              title="Slug"
              text={trimmedURL ?? ""}
            />
            <List.Item.Detail.Metadata.Label
              title="Status"
              text={data?.object.metadata.read ? "Read" : "Unread"}
            />
          </List.Item.Detail.Metadata>
        }
      />
    )
  );

Actions

Finally, with Actions we’ll be able to easily visit one of our bookmark links or copy it to the clipboard to share elsewhere. We can do a lot of powerful things with Actions, and the full version of this that you can get from the Raycast Store utilises your Cosmic write key to update objects through the updateOne() and deleteOne() methods. But for this tutorial, we’re focused on read-only.

So again, like with our Detail view, we’ll fetch the same data in the same way (we’re also passing the same props down to it!).

function Actions(props: { id: string; title: string }) {
  const { bucketSlug, readKey } = getPreferenceValues<Preferences>();

  const { data } = useFetch<SingularObject>(
    `https://api.cosmicjs.com/v3/buckets/${bucketSlug}/objects/${props.id}?read_key=${readKey}&depth=1&props=`
  );

  if (!data?.object || data === null) {
    return null; // Return null when data is not available
  }

{/* The rest of our code */}

}

In order to render these actions in the UI, we again have super helpful components from Raycast.


return (
    <ActionPanel title={props.title}>
      <ActionPanel.Section>
        {data?.object && (
          <Action.OpenInBrowser
            url={data?.object.metadata?.url}
          />
        )}
        {data?.object.slug && (
          <Action.CopyToClipboard
            content={data?.object.metadata?.url}
            title="Copy Link"
            shortcut={{ modifiers: ["cmd"], key: "." }}
          />
        )}
      </ActionPanel.Section>
      <ActionPanel.Section>
        <Action
          title="Open Extension Preferences"
          icon={Icon.Gear}
          onAction={openExtensionPreferences}
        />
      </ActionPanel.Section>
    </ActionPanel>
  );
}

Notice that for Action.OpenInBrowser we don’t have to declare a keyboard shortcut or define a specific browser, Raycast handles all that for us by default the main action to ↵. You can override this by copying the shortcut={} code that we have in the Action.CopyToClipboard. Just note that modifiers is an array of specific options, so make sure you check the docs.

Step 5: Putting it all together

Here’s the full code as one nice big chunk.


import {
  Action,
  ActionPanel,
  Icon,
  List,
  getPreferenceValues,
  openExtensionPreferences,
  Toast,
  showToast,
} from "@raycast/api";
import { useFetch } from "@raycast/utils";
import React from "react";

interface Preferences {
  bucketSlug: string;
  readKey: string;
  writeKey: string;
}

interface ObjectsList extends React.ComponentPropsWithoutRef<typeof List> {
  objects: [
    {
      id: string;
      type: string;
      title: string;
      slug: string;
      metadata?: {
        snippet: string;
        url: string;
        read: boolean;
      };
    }
  ];
}

interface SingularObject extends React.ComponentPropsWithoutRef<typeof List> {
  object: {
    id: string;
    type: string;
    slug: string;
    title: string;
    metadata: {
      published: string;
      snippet: string;
      url: string;
      read: boolean;
    };
  };
}

export default function Command() {
  const { bucketSlug, readKey } = getPreferenceValues<Preferences>();
  const { data, isLoading } = useFetch<ObjectsList>(
    `https://api.cosmicjs.com/v3/buckets/${bucketSlug}/objects?query=%7B%22type%22:%22bookmarks%22%7D&read_key=${readKey}&depth=1&props=`
  );

  return (
    <>
      <List isLoading={isLoading} isShowingDetail>
        {data?.objects.map((object) => (
          <List.Item
            key={object.id}
            title={object.title}
            detail={
              <ObjectDetail id={object.id ?? ""} title={object.title ?? ""} />
            }
            actions={
              <Actions
                id={object.id ?? ""}
                title={object.title ?? ""}
                read={object.metadata?.read ?? false}
              />
            }
          />
        ))}
      </List>
    </>
  );
}

function ObjectDetail(props: { id: string; title: string }) {
  const { bucketSlug, readKey } = getPreferenceValues<Preferences>();

  const { data, isLoading } = useFetch<SingularObject>(
    `https://api.cosmicjs.com/v3/buckets/${bucketSlug}/objects/${props.id}?read_key=${readKey}&depth=1&props=`
  );

  if (!data?.object) {
    return null; // Return null when data is not available
  }

  const regex = /.*https:\/\/www\.|http:\/\/www\.|https:\/\/|http:\/\/|\/.*$/gm;
  const trimmedURL = data?.object.metadata.url.replace(regex, "");

  return (
    data?.object && (
      <List.Item.Detail
        isLoading={isLoading}
        markdown={
          `## ${props.title}` +
          "\n\n" +
          `${data?.object.metadata?.snippet ?? ""}`
        }
        metadata={
          <List.Item.Detail.Metadata>
            <List.Item.Detail.Metadata.Label
              title="Slug"
              text={trimmedURL ?? ""}
            />
            <List.Item.Detail.Metadata.Label
              title="Status"
              text={data?.object.metadata.read ? "Read" : "Unread"}
            />
          </List.Item.Detail.Metadata>
        }
      />
    )
  );
}

function Actions(props: { id: string; title: string }) {
  const { bucketSlug, readKey } = getPreferenceValues<Preferences>();

  const { data } = useFetch<SingularObject>(
    `https://api.cosmicjs.com/v3/buckets/${bucketSlug}/objects/${props.id}?read_key=${readKey}&depth=1&props=`
  );

  if (!data?.object || data === null) {
    return null; // Return null when data is not available
  }

  return (
    <ActionPanel title={props.title}>
      <ActionPanel.Section>
        {data?.object && (
          <Action.OpenInBrowser
            url={data?.object.metadata?.url}
          />
        )}
        {data?.object.slug && (
          <Action.CopyToClipboard
            content={data?.object.metadata?.url}
            title="Copy Link"
            shortcut={{ modifiers: ["cmd"], key: "." }}
          />
        )}
      </ActionPanel.Section>
      <ActionPanel.Section>
        <Action
          title="Open Extension Preferences"
          icon={Icon.Gear}
          onAction={openExtensionPreferences}
        />
      </ActionPanel.Section>
    </ActionPanel>
  );
}

Conclusion

Note: The initial Raycast Extension setup provided here is lifted from their Getting Started docs.
You can also find out more about using Cosmic via the Cosmic Docs.

Now you should have a good understanding of Raycast extensions and Cosmic, and a good idea of how to leverage them both to make your own custom extensions. If you end up building anything awesome using both Raycast and Cosmic, share it with us on Twitter!

Resources:

Getting DRY with Figma plugins

Karl — Sat, 15 May 2021 00:00:00 +0000

There’s a concept called DRY in development. It means Don’t Repeat Yourself and is all about code reduction through declaring and reusing shared resources. Say for example that I have a simple conditional statement that checks for all the correct node types in a Figma plugin to determine if it can make adjustments. I could do the following to do it:

if (node.type === "FRAME") {  
  const frame = figma.createRectangle()  
  frame.width = node.width  
  frame.height = node.height

// and so on

}

if (node.type === "GROUP") {  
  const frame = figma.createRectangle()  
  frame.width = node.width  
  frame.height = node.height

// and so on

}

if (node.type === "ELLIPSE") {  
  const frame = figma.createRectangle()  
  frame.width = node.width  
  frame.height = node.height

// and so on

}

But what I’m doing there is redeclaring the same information multiple times, what a waste of compute power. So instead I can bundle these into one. It’s difficult to use the !== declaration because so many things can need exclusion, so the best way is to use our friend .includes().

const nodeTypes = ["FRAME", "GROUP", "ELLIPSE"] 
  if (nodeTypes.includes(node.type)) {     
  const frame = figma.createRectangle()     
  frame.width = node.width     
  frame.height = node.height   

// and so on

}

// ...

In design we can do a similar thing using atomic components, building up reusable assets as Lego blocks to avoid having to keep creating new assets. However, we can also take it a step further into the productivity side of design using Figma plugins.

Figma Plugins, what’s the deal?

Well, you’ve had a sneak peek at a bit of Figma plugin code above. Figma plugins use Typescript under the hood to allow you to create, modify and elevate your Figma project.

As you probably know, I’m an evangelist for the “Designers should Code” philosophy, at least, I feel Designers should understand some code. And I’ve taken that further to believe that knowing how to write enough Javascript to build your own Figma plugins is a superpower all Designers should try to harness.

Figma plugins enable Designers to perform at optimum operational capacity without the burden of loads of admin overhead. Now there are tonnes of available plugins in the Figma Community but that doesn’t mean you can find one to solve your problem, some issues are just too unique to your use case.

At HomeHero, we’re using a bunch of custom Figma plugins that I’ve written (including the ones I’ve actually released) to better maintain our files. I’ll cover some of these below.

Ultimately, Figma plugins stop us from repeating ourselves with common admin tasks to clean up our files, they allow us to focus on designing the best experience instead of organising our contents.

The ‘Gist’ of how plugins work

A couple of these Gists use the Scripter plugin to work as it has its own API to simplify some bits, grab it here. Of course, you can use the standard Figma API to perform any of this too, it just might be a little more verbose.

HomeHero TextLint

One of the first plugins I wrote for us was aimed at simplifying text linting. We have a bunch of phrases we write in our designs regularly thanks to our industry, and there are many times that we mistype them and this sometimes makes its way to the product (oh dear!). To avoid that, I’ve written a super simple linter that parses the document and updates all text characters that match my arrays. It’s not the cleanest or best code, but it saves us a bunch of time.

const find = ["Move in", "move in", "Homehero", "wifi", "Wifi", "WiFi"];
const replace = ["Move-in", "move-in", "HomeHero", "Wi-Fi"];

const layers = figma.currentPage.findAll((node) => node.type === "TEXT");
figma.currentPage.selection = layers;
const { selection } = figma.currentPage;

async function lintTextNodes(): Promise {    
  figma.root.children.flatMap((pageNode) =>        
  pageNode.selection.forEach(async (node) => {          
  if (layers.length > 0 && node.type === "TEXT") {              
    await figma.loadFontAsync(node.fontName as FontName);              
    node.characters = node.characters.replaceAll(find[0], replace[0]);              
    node.characters = node.characters.replaceAll(find[1], replace[1]);              
    node.characters = node.characters.replaceAll(find[2], replace[2]);              
    node.characters = node.characters.replaceAll(find[3], replace[3]);              
    node.characters = node.characters.replaceAll(find[4], replace[3]);              
    node.characters = node.characters.replaceAll(find[5], replace[3]);          
   }         
  return Promise.resolve("Done!");       
  })  
 );    

if (layers.length === 0) {          
  return Promise.reject("No layers selected");  
}}  

lintTextNodes();  
figma.notify("All linted");  
figma.closePlugin();

HomeHero CropAll

The second was a quick way to set all images to "FILL" mode and apply a resize constraint on them. It’s not full-proof, but it gets all your images to the same basic starting point. We needed to do this because we have a tonne of images we use for our Picks feature and they all need to be set to the same size to reduce bandwidth when served to the app.

When you have over 400 images, you want this!

const layers = figma.currentPage.findAll(isImage);
figma.currentPage.selection = layers

for (let shape of await find(selection(), n => isImage(n) && n)) {
// Update image paints to use "FILL" scale mode  
shape.fills = shape.fills.map(p => isImage(p) ? {...p, scaleMode: "FILL",} : p)  
shape.resize(375, 375)}

HomeHero Slide Export

Finally, we work in Figma to create our investor slide decks and other slides to share our design progress or lunch and learns. It’s great but it’s annoying when you need to then turn these into an exported set of slides.

Luckily, we can use Figma plugins to apply some simple settings to make this happen and then export those Frames for others to use (you can even use my Lazy PDF app to compress it into a lossless PDF afterward).

const layers = figma.currentPage.findAll(); 
const frames = layers.filter(isFrame);   

async function renameFrames() {     
 let items = frames; if (items.length > 0) {     
 for (const node of items) {       
  if (node.type === "FRAME") {         
    node.name = ((node.name).substr(0,2) != 'Slide/') ? node.name = "Slide" + "/" + node.name : node.name; }       
  }     
 }}         

renameFrames();     

figma.currentPage.selection = layers.filter((n) => n.name.startsWith("Slide/"));     
const { selection } = figma.currentPage;

function hasValidSelection(nodes) { return !(!nodes || nodes.length === 0); } 
const settings = [ 
{ format: "PNG", suffix: "@1x", constraint: { type: "SCALE", value: 1 } }, 
{ format: "PNG", suffix: "@2x",constraint: { type: "SCALE", value: 2 } }, 
{ format: "PNG", suffix: "@3x", constraint: { type: "SCALE", value: 3 } }, 
{ format: "SVG", suffix: "" },]; 

async function main(nodes): Promise {   
  if (!hasValidSelection(nodes)) return Promise.reject("No valid selection");   

  for (let node of nodes) {     
    node.exportSettings = settings;   
  }     

return Promise.resolve("Done!"); 
} 

main(selection).then((res) => figma.closePlugin(res));

Published plugins

Beyond these, I’ve written a bunch of small utility plugins to make designer life easier. You’ll see them all on my Plugins.run site, but you can find them all here also.

In the end, it’s all about saving time

Ultimately, we all want to save time and not do consistent, repetitive tasks each day. Figma plugins, and having the knowledge to write them, can be that solution for you. I can’t count how many countless hours I’ve saved myself by writing the plugins I have and using plugins others have written too.

If you want to get started with Figma plugins, try out my Gists, or, follow this awesome tutorial from Dan Hollick who shares a lot of my feelings about designers and code.

If you do end up creating anything awesome for your team, please send me a note and share some Gists! I love seeing what people are up to and seeing how I can adapt and utilise what they’ve done like I hope people do with my shares.