DEV Community: David Dias

I Ditched My AI Agent Dashboard for Obsidian

David Dias — Sun, 08 Feb 2026 15:46:00 +0000

I spent a few days building a React dashboard. Dark mode, real-time updates, graphs showing agent activity across my network. My agents helped me build it. It looked incredible. I showed it to a friend and they said "wow, that's impressive." Then I deleted the entire repository.

Something felt wrong. I couldn't put my finger on it at first. But the more I worked with it, the more I realized I was solving the wrong problem. I was building a UI that will probably be obsolete at some point. With the ultra-fast evolution of OpenClaw, it's another app I would have to maintain.

The Dashboard Trap

The idea seemed smart. I have multiple AI agents running on different machines. They need coordination. They need to share state. They need to report what they're doing. What better solution than a beautiful dashboard?

So I built one. WebSocket connections. Agent status indicators. Task queues visualized with drag-and-drop. I even added a dark mode toggle because of course I did.

Then came the maintenance. One agent would fail to report and I'd spend an hour not knowing it had failed silently. The dashboard itself became a project that needed its own dashboard.

It hit me during a weekend when I wanted to check on my agents but couldn't because the server was down. I was locked out of my own system because the UI layer failed. That's when I realized: I had built a cage for myself.

The Problem

If you look around. Everyone building AI agents is also building some sort of complex UIs to coordinate them. We have agent frameworks with admin panels. Status dashboards with graphs and charts. It's beautiful, but is it necessary?

Agents are programs. They can read files. They can write files. They don't need a "dashboard." They need data. The dashboard is for us. And we already have tools to read and write data.

The problem isn't coordination. It's that we're over-engineering the coordination layer because that's what we're used to doing.

The "Dumb" Solution

I deleted the React dashboard.

Then I opened Obsidian.

I created a folder called 07-agents/ in my vault. Each agent got its own subfolder with three files: SOUL.md (its personality and purpose), a kanban-style task list, and a reports/ folder.

That's it. No UI. No database. Just markdown files in a folder structure.

I updated AGENTS.md and created a skill to ensure that the agents knew what, how and where to create files.

How It Actually Works

My setup is intentionally simple:

Separated Linux server with OpenClaw (on a small NUC)
Mac with Obsidian: I work on my laptop. This is where I read reports, assign tasks, and review what the agents are doing.
rsyncover Tailscale: every 5 minutes, a cron job syncs the 07-agents/ folder between my server and my laptop using rsync over SSH through Tailscale. No complex sync engine. Just a command that runs in the background.
Agents read/write markdown files: when an agent needs to report something, it appends to a markdown file. When it needs a new task, it reads its task list. Just file I/O.

Jarvis, my main agent ensures every X mins, that the agents know they have a folder of files to work with and they successfully do their tasks.

The Setup

I use the PARA method for my Obsidian vault, so agents live in their own corner: 07-agents/. Each agent has a consistent structure:

SOUL.md. The agent's personality, capabilities, and boundaries. This is their definition file.
Task List.md. A kanban board in markdown. Backlog, In Progress, Review, Done.
reports/. A folder where the agent dumps its daily reports, findings, and outputs.
knowledge/. Reference material the agent needs to do its job.

I use Dataview to create dashboards. A simple query gives me a view of all in-progress tasks across all agents. Another query shows me recent reports. It's not real-time in the web dashboard sense, but it's real enough. I refresh when I want updates.

Real Benefits

This setup has advantages I didn't anticipate:

Offline capable: I can work on my laptop without internet. The agents keep running. When I reconnect, rsync catches up. No sync conflicts, no "you have unsaved changes" warnings.
Plain text = future proof: markdown isn't going anywhere. Even if Obsidian disappeared tomorrow, I'd still have readable files.
No UI maintenance: I don't maintain a UI anymore. The UI is Obsidian, which someone else maintains. I just write markdown.
Portable: I can access agent data from any device that reads text files. My phone. A tablet. A borrowed computer. No authentication flow required.
Git-friendly: the entire coordination layer can be version controlled. I can see exactly what an agent did yesterday by looking at git history.

Technical Deep Dive

For those who want to try this, here's the actual setup:

The rsync command is simpler than you'd expect:

rsync -avz --delete --exclude='.git' \
  -e "ssh -i ~/.ssh/agent_sync" \
  ~/obsidian/07-agents/ \
  server:/home/agents/vault/

(I confess that my agent did the whole setup...) 😬

I run this every 5 minutes via cron. The --exclude='.git' is important. I learned that the hard way when git corruption caused sync issues.

Conflict resolution is simple: newer wins. rsync handles this. If I edit a task on my laptop while an agent updates its status, whichever finishes last persists. In practice, this almost never causes problems because agents mostly append to files, and I mostly edit task lists.

Health monitoring comes through Telegram. Each agent sends me a daily message: tasks completed, any blockers, and a status emoji. If I don't get the message, something's wrong. It's lo-fi, but it works.

The key insight: Agents don't need to know about each other. They just need to know about files. If Agent A writes a report that Agent B needs to read, that's just filesystem permissions. No message bus required.

Why This Wins

I spent a few days building complexity with agent help and two hours replacing it with simplicity. The simple solution works better.

The dashboard I built was impressive. It was also unnecessary. Agents don't need dashboards. They need data. Humans don't need real-time graphs. We need context.

Markdown files in a synced folder give both groups exactly what they need. Agents get structured data they can parse. Humans get readable documents they can understand. No translation layer required.

The best part? When something breaks, I can debug it with cat and grep. I don't need to check server logs and database connections. I just look at the files.

Sometimes the dumb solution is the smart one.

What would you simplify in your setup if you weren't afraid of looking unsophisticated?

Getting Started with llms.txt

David Dias — Thu, 27 Feb 2025 05:04:42 +0000

Learn how to implement llms.txt in your website or documentation

What is llms.txt?

The llms.txt file is a proposed standard that helps AI models better understand and interact with your website's content. Unlike robots.txt or sitemap.xml, it's specifically designed to enhance AI interactions by providing structured content overviews and navigation paths.

Purpose and Benefits

Enhanced AI Understanding: Provides a structured overview of your website content, helping AI systems understand your site quickly and accurately
Efficient Information Retrieval: Enables AI systems to locate and retrieve relevant information efficiently
Improved Contextual Understanding: Reduces misinterpretation by providing context and relationships between content
Better User Experience: Leads to more accurate, context-aware responses when users interact with AI about your content
Overcoming Context Limitations: Helps AI systems work within their context window limitations by providing streamlined content access

How llms.txt Differs from robots.txt and sitemap.xml

While these files might seem similar, they serve distinct purposes:

robots.txt: Focuses on controlling search engine crawler access but doesn't help with content understanding
sitemap.xml: Lists all indexable pages without providing context or helping with content processing
llms.txt: Specifically addresses AI-related challenges by providing content structure in a format optimized for AI processing

The llms.txt Specification

The specification defines two distinct files:

/llms.txt: A streamlined view of documentation navigation to help AI systems quickly understand a site's structure
/llms-full.txt: A comprehensive file containing all documentation in one place

Both files use Markdown formatting, which provides a natural hierarchy that AI models can easily parse.

Basic Implementation Guide

1. Create the File Structure

The llms.txt file uses Markdown with a specific structure:

# Your Website/Project Name

> A brief description of your website or project

## Documentation

- [Getting Started](/docs/getting-started) - Guide for new users
- [API Reference](/docs/api) - Complete API documentation
- [Tutorials](/docs/tutorials) - Step-by-step guides

## Examples

- [Basic Implementation](/examples/basic) - Simple integration example
- [Advanced Features](/examples/advanced) - Using advanced capabilities

## Optional Resources

- [Community Forum](/community) - Get help from other users
- [Change Log](/changelog) - Track updates and changes

2. Place the File in the Correct Location

Save the file as llms.txt in your website's root directory, ensuring it's accessible at yourwebsite.com/llms.txt. If you're creating a comprehensive version with all your documentation, save it as llms-full.txt.

3. Add HTTP Headers (Optional but Recommended)

Add the following HTTP header to your server configuration:

X-Robots-Tag: llms-txt

4. Verify Implementation

Test your implementation by:

Accessing yourwebsite.com/llms.txt
Checking HTTP headers
Validating the file format

Using llms.txt with AI Systems

Currently, most AI models don't automatically discover and index llms.txt files. To use your llms.txt file with AI systems:

Direct Link: Provide the AI with a link to your llms.txt file
Manual Copy: Copy the contents of your llms.txt file directly into your prompt
File Upload: Use the AI tool's file upload feature if available

As adoption increases, more AI systems will likely integrate automatic discovery of llms.txt files.

Where To Find a list of all llms.txt files?

llms.txt hub is rapidly becoming a popular open-source hub tracking all the websites that have implemented the llms.txt and llms-full.txt standards. Updated regularly, this comprehensive directory allows you to:

Discover real-world implementations across various industries and platforms
Study how leading organizations structure their llms.txt files
Access the latest news and developments related to the standard
Find open-source tools, plugins, and resources for implementing llms.txt on your own website

By exploring this directory, developers and content creators can observe implementation patterns, stay informed about best practices, and connect with the growing community of websites optimizing their content for AI systems through the llms.txt standard.

Generation Tools

Several tools can help you generate llms.txt files:

llmstxt by dotenv: Open source CLI tool that generates llms.txt based on a site's sitemap.xml file.
llmstxt by Firecrawl: Uses Firecrawl to generate a llms.txt file.
Mintlify: Documentation platform with llms.txt generation

Real-World Examples

Many organizations have already adopted the llms.txt proposed standard:

Cloudflare: Impressive and extensive documentation about all the Cloudflare services
Anthropic's llms.txt: All their documentation and prompt library
Perplexity's llms-full.txt: A comprehensive implementation all their documentation and content website
ElevenLabs: All the documenation about their API and product guides

Best Practices

Keep it Updated: Regularly update your llms.txt file as your website structure changes to ensure AI systems have the most current information.
Use Clear Markdown Structure:
- Start with an H1 project name
- Include a blockquote summary
- Use H2 headers to organize documentation links
- Provide brief descriptions for each link
Be Selective: Focus on the most important resources in llms.txt, using the Optional section for less critical content.
Test with AI Systems: Verify that AI models correctly interpret and navigate your content based on your llms.txt file.
Optimize for AI Processing: Remove non-essential markup and scripts in llms-full.txt to help AI models focus on the important content.

Resources

Beyond User Testing: Leveraging Frontend Experience

David Dias — Sat, 10 Jun 2023 20:49:00 +0000

User testing is a crucial tool for gathering feedback on a product, but it's not enough to truly understand and improve user engagement. For the past 13 years, I have been building multi-language platforms for international brands and for a wide variety of users. Even in a space that constantly changes, where users have evolving needs, it's important to also acknowledge the role that experience plays in understanding them.

Marvin Meyer on Unsplash"/>

Being a Front-End Developer gave me and all my colleagues around the world a unique perspective on user experience. We understand how small design decisions can have a big impact on the user experience, and we have a deep understanding of how users interact with products. By leveraging our experience in front-end development, we can help create products that are not only effective but also enjoyable to use, leading to increased user satisfaction and loyalty.

The limits of user testing

User testing is a critical component of product development that can help identify usability issues and gather feedback from real users. By testing products with representative users, product teams can gain valuable insights in how users interact with their interfaces and what their pain points are. Whatever you use services like User Testing, or your own user testing directly with regular users, user testing also possess some limits that can’t be overlooked.

For example, users may not always be able to articulate their needs and preferences accurately, or identify more obvious usability issues that sometimes are more subtle or hidden. User testing is also typically conducted in a controlled environment, which may not always accurately reflect real-wold usage scenarios.

What about people that don’t use technology in a daily basis?

Usually user testing is done by a certain user group or demographics and don’t include 100% of all users. From my point of view, user testing can’t be really complete without testing with people with disabilities. For people with experience in doing accessibility testing with real users, I’m sure you will agree that.

User testing can lead to success or failure

Through Internet history, user testing had lead to create successful products:

Slack (which I daily use) is a popular communication tool. During its development, Slack's team conducted user testing to identify usability issues and gather feedback from its target users. This feedback helped them make improvements to the platform, resulting in a product that was easier to use and more engaging for its users.
Dropbox is a cloud storage platform that allows users to store, share, and collaborate on files. Dropbox's team used user testing to identify pain points and improve the user experience, resulting in a product that was more intuitive and engaging for its users.
And a lot more…!

But user testing can also fail to uncover critical usability issues which can contribute to the failure of some projects:

Google Wave was a communication and collaboration platform that was introduced in 2009. User testing suggested that users would appreciate the platform's advanced features and integration with other Google products, but when it was released to the market, users found the platform confusing and difficult to use, leading to low adoption rates and eventually the discontinuation of the product in January 2018.
The Amazon Fire Phone was a smartphone introduced by Amazon in 2014. User testing suggested that users would appreciate the phone's unique features, such as the dynamic perspective display, but when it was released to the market, users found the phone overpriced and underwhelming, leading to poor sales and eventually the discontinuation of the product. The lack of empathy towards the users needs was also part of the reasons why it failed.
Twitter timeline algorithm: In 2016, Twitter also faced public outrage when they introduced an algorithm-based timeline, which did not align with users' preferences for a chronological timeline that allowed them to see real-time tweets in ascending order.

Building a successful project is not an easy task, a lot of factors can influence the success or the failure of a new product. Nowadays, users have different needs. Users switch faster to competitor then before, we have daily examples of that.

User testing is one tool in companies belt that should be used as often as possible, but shouldn’t be the only one.

Leveraging Front-End experience

Front-End Developers (FED) are not just coders. Usually seen as the ones that “just” integrate designs into HTML, CSS and JavaScript, their t-shape personalities is often times overlooked (not all FES have t-shape skills though).

A FED can play a critical role in creating engaging user experiences.

Collaboration and communication for better user engagement

As I said in my previous article about Front-End Developers, Web and UX/UI Designers collaboration, collaboration and communication is key in building a successful product.

This collaborative approach allows different perspectives to merge and create a more holistic vision of the product. As Front-End Developers, we have the unique position of working at the intersection of design and technology. We are often the ones who bring the designers' visions to life while ensuring that the product remains functional and user-friendly.

Front-end development is about more than just making things look good. It's about creating a seamless and intuitive interface that guides users through a product. Every button, every transition, every piece of interactive content is a chance to engage users and keep them invested in the product.

The Benefits of Leveraging Front-End Experience

Front-end developers have a deep understanding of user behavior, as they are responsible for creating the interactive elements that users engage with. They can use this knowledge to create more engaging user interfaces and to guide user testing to focus on areas of the product that are most likely to affect user engagement.

Beyond just implementing designs, a seasoned FED can provide insights and suggest improvements to the UX/UI designs based on their knowledge of what is technically feasible and what would create a smoother user journey. They can spot potential pitfalls in the designs that might be overlooked during user testing.

For example, a developer might notice that a particular design element could cause issues on certain devices or browsers. They might also suggest an alternative way of implementing a feature that enhances the user's experience. I have been advocating about accessibility for years now. Last year, I became CPACC certified and I continue to advocate for accessibility in my daily work. Not everyone understand what web accessibility is and how it impacts users. It takes time and effort to educate people about it.

The Future of User Engagement

As technology advances, users' expectations also rise. They demand faster, smoother, and more intuitive interfaces. User testing will always be a vital tool for gathering feedback, but to meet these evolving demands, we need to go beyond testing.

Incorporating the front-end developer's expertise into the design process and user testing can help create a product that not only meets the users' needs but also provides an engaging and satisfying experience.

We must continue to push the boundaries, experiment with new technologies, and constantly seek ways to better understand and improve user engagement. Only by doing this can we hope to create products that users will love to use.

Front-End Developers bring a valuable perspective to the product development process. Let's use it to its fullest potential to create engaging, user-friendly products. After all, the success of any product lies in the satisfaction of its users.

At the end, user engagement is not just about the single experience of a product but the entire journey. It's about creating an engaging, intuitive, and satisfying journey that users want to return to again and again. And Front-End Developers play a crucial role in crafting this journey.

Remember, user testing is a part of the journey, not the destination. We must use all the tools at our disposal, and that includes leveraging the front-end development experience to truly understand and improve user engagement.

Let's continue to build with the user in mind, always striving to enhance their journey, their experience, and ultimately, their engagement.

Resources

"The Importance of User Testing in Product Design" by Smashing Magazine
"Experience Design: What It Is and Why It Matters" by Adobe XD Ideas
"Why User Experience Matters to Front-End Developers" by UX Design
"The Benefits of Combining User Testing and UX Design" by UserTesting
"Why User Experience (UX) is Vital for Front-End Developers" by Echobind

9 Best Practices & UX improvements for the two-factor authentication (2FA)

David Dias — Fri, 26 Feb 2021 00:30:00 +0000

In 2023 alone, cybercriminals will steal 33 billion records. It takes 196 days on average to identify a data breach. The cost of a data breach will reach $150 million by 2020...
These numbers may be scary but they are only previsions. Things could be much worse in the near future. Security has become a hot topic these last years, almost everyone on the planet has already heard about a company data breach or even a friend that lost his Facebook account because someone hacked it! No one is completely safe nowadays.

I've recently spent multiple hours ensuring that all the accounts I possess use a unique password, complex and long with at least 20 characters and with the two-factor authentication (2FA) enable if present. I've discovered so many disparities between companies and so many issues in terms of features and user experience. I wanted to share with you in this article, what I believe are the best and recommended features for any website or company that takes the security of its users seriously.

1. Offer two-factor authentication options

That is the starting point.

If you care about your users or customers, you should give them the choice to activate the two-factor authentication. On around 800 websites where I have an account, only 5% offer a 2FA option. Some may argue that if you don't have highly sensitive information, it may be overkill to offer the 2FA. But any personal information could be considered sensitive.

If you care about your users and their security, give them the option to enable the 2FA. Period.

2. Don't force the users to choose only one 2FA method

Google, Facebook, Twitter... they all offer simultaneous ways for 2FA: text message, authentication app and security key. More commonly, at least in a text message and authentication app, the security key seems to be set up only on certain services.

But I've been surprised to see Etsy, even they use toggles on their UI, to force you to only choose one of the options. I'm not even sure if it was originally designed to work like that.

Bit.ly and booking.com in other hand only allow you to use your phone as a 2FA device. So if you lose your phone and your email access, you could be screwed.

Mailchimp and Tumblr, on the contrary, only offer 2FA using an authentication app.

Zapier has an awesome step by step 2FA setup, probably one of the best I found. They offer multiple complementary ways and specifically tell you "in the event you get locked out of your account and have lost both your authentication device and recovery codes". The user understands that providing his phone number is an additional way to ensure he/she can access his account in case he/she lost the other ways to connect to their web app.

3. Make the QR code an image

I have been using 1Password for quite some time now and the modal that scans the QR code doesn't always find the QR code. In that case, I found myself drag and dropping the QR into that modal to be recognized. But it only works when the code is an image.

I would recommend having it as a format image that can be saved / drag and dropped.

Reddit for example doesn't have their QR code as an image. Fortunately, everyone offers the text version of the QR code that you can use in your authentication application.

4. Keep the code you send by email in the same format as requested in your app or website

This one only happened to me once. It happened with Instagram.

When Instagram sends a "verification code" by SMS, they included a space. If you copy-paste that code where it's required, first the input doesn't want the space and the last digit is not included in your paste. It's an annoying issue that could be fixed easily!

5. Give the option to have recovery/backup codes

Sounds weird when said at loud but a lot of websites don't offer backup/recovery codes when you enable the 2FA. This was a surprise for me at first, 2FA means you will always have backup codes in case you lost access to your phone, email or the app you use to generate the random number. Nowadays, some websites don't offer that option. I tend to be really careful with those.

Kickstarter and WPEngine are examples of websites that don't offer you any recovery/backup codes. I hope they could improve that.

6. Always give the option to download the recovery codes

Most of the websites propose to copy the recovery codes. This is not the best option.

It's nice to have it, sure, but it's not enough. I personally store all my recovery codes in multiple places: one is the vault from Dropbox. Having just to drag and paste a simple text file is easy and fast.

If you offer only the option to copy, then you could be forcing the user to:

1) open the text editor
2) paste the codes
3) give a name
4) save the file on your device Technology is there to save user's time.

Slack for example allows you to "Print codes" but not download them. Why not? I have to generate a PDF instead of my simple text file. Not the best user experience.

7. In the recovery code text file, always write which platform these codes are coming from

Even Facebook can make mistakes and this one is important for me. Currently, if you download the recovery codes from Facebook, you open the file and you can't find any mention of Facebook or the name of the account. The file name facebook_recovery_codes is helpful but in my opinion, not enough. The name of the account and the name of the platform should be a minimum.

And to make it more useful, adding the date when the codes were generated could also be added.

Google which is a good example, uses your username in the name of the file, and also adds:

SAVE YOUR BACKUP CODES
Keep these backup codes somewhere safe but accessible.

LIST OF CODES

(email@gmail.com)

* You can only use each backup code once.
* Need more? Visit https://g.co/2sv
* These codes were generated on: Date, 2021.

8. Allow the user to regenerate recovery/backup codes

It's essential to give the user the ability to regenerate recovery codes. Some don't offer this useful option.

9. Offer more than one code (maybe?)

This one is less important but I still wanted to mention a key difference in terms of recovery/backup codes.

Most of the companies only offer one code vs a list of multiples codes that can be used. It's hard for me to defend one approach vs the other one. I just know that I feel better when I have more than one code.

About security keys

Security keys are the less common way to secure your account. If you are a public figure or someone with a high level of responsibility, having a security key could give you a little bit more peace of mind. But for a normal user, it may be overkill. Nonetheless, I wanted to maximize the security of my accounts and recently bought the Titan Security Key from Google. The USB version works on any computer and I use the Bluetooth version in case I'm on my iPhone or iPad.

They both are not cheap, but security should be part of your "unlimited budget", the same as for food.

Conclusion

I'm not a security expert and have limited knowledge in terms of security. But as a Software Engineer and particularly a user, I believe we have a long way ahead until most of the platforms implement all the best practices and features to ensure secure access for all users.

Recap:

Offer two-factor authentication options
Don't force the users to choose only one 2FA method
Make the QR code an image
Keep the code you send by email in the same format as requested in your app or website
Give the option to have recovery/backup codes
Always give the option to download the recovery codes
In the recovery code text file, always write which platform these codes are coming from
Allow the user to regenerate recovery/backup codes
Offer more than one code (maybe?)

Thanks for reading, I hope these suggestions would help you to have a better UX and improve your 2FA implementation.

Feel free to ask me anything in the comments below!

How to deploy your Next.js app on Netlify using Github Actions

David Dias — Thu, 21 Jan 2021 21:58:24 +0000

I've recently spent some time working with Next.js projects. Once my projects are done, the next logical step is to deploy these apps to be accessible to the world.

I have naturally used the Vercel platform, which couldn't be easier to use and deploy your application with ease. Then I tried AWS Amplify, which I particularly love but for now, requires you to use the Serverless Framework if you want to benefit from Server Side Rendering (SSR) capabilities.

Then, I remembered that Netlify has added support for Next.js, including dynamic routes, Preview Mode and more since November 2020. It was time for me to try it! But I also wanted to have a real CI/CD in place, to test my code and do more actions before deploying to Netlify. That's where Github Actions came to the rescue!

I'm going to describe in this article, all the steps you need to take to deploy your Next.js application on Netlify using Github Actions.

The full version of the project can be found on Github.

Create a new Next.js App and push it to Github

As always, you need to have a recent version of Node and NPM installed on your machine. I personally recommend using NVM since it simplifies having multiple active Node.js versions.

To create a new Next.js project, type this command in your CLI:

npx create-next-app name-of-your-app

# move into the app's root directory
cd ~/path-to-projects/name-of-your-app/

This will install a new application using a basic Next.js boilerplate. Don't forget to move to your app root folder before launching any next commands.

Once your Next.js project is locally created, you can create a new project on Github and push the code generated.

(For those you are new to coding, feel free to follow these steps to create a new repository on Github.)

Setting up your Netlify project

There are 2 ways of creating a new Netlify project:

Creating a project online here
Using the Netlify CLI.

Let's use the CLI this time, I'm sure you already created a new project in the past using the Netlify interface.

Let's start by installing netlify-cli globally:

npm install netlify-cli -g

Then check if the installation succeeds, confirming with this command:

netlify

Netlify account authentication

Now you need to link your computer with your Netlify account. To authenticate with Netlify, you need to run this command:

netlify login

This will open a new tab in your browser where you'll need to "Authorize your Application" and then grant access to Netlify CLI.

In case you already logged in previously, the console will output:

Already logged in via netlify config on your machine

Netlify project creation

Now that your CLI is authorized to communicate with your Netlify account, it's time to programmatically create a new project:

# create a new Netlify site using the Netlify shortcut: ntl
ntl init

The first question you are asked is if you want to connect this directory to an existing Netlify site or create & configure a new site. Choose Create & configure a new site:

Then you have to choose your team:

Choose the name of your application:

After entering the name of your project, the site is created and few URLs populated the CLI which gave you access to your admin URL, the URL of your site and the Site ID. Keep the site ID aside, you will need that number later on.

For the next 3 questions (build, start and function), insert a space. We are not going to directly use the NPM scripts, our Github actions will later trigger each command.

Finally, automatically create a netlify.toml file, which we will edit later. If your respond no, you can still create that file manually at the root of your project.

Once you provided an answer to all the questions, your terminal should look like this:

Updating our Netlify project

It's now time to change some options on our Netlify project. Open directly your project on Netlify with this command:

ntl open

You should see that our production deployment failed. You don't have to worry, this is totally normal. We need to disable our automatic build because our Github Actions will take care of it.

Go in your Settings > Build & deploy. Click on Edit settings and Stop builds. Save.

Just below, go to the Deploy contexts section and select None for the Deploy previews.

Don't worry, like the build, we will create our preview URL using Github actions.

Enable server-side rendering on Netlify

If you have been using Next.js you are aware of the capability to do the server-side rendering. But usually, you will need to configure a Node server and that's something we don't want to have to deal with. Around October 2020, the Netlify team started working on next-on-netlify, a utility to enable SSR in Next.js on Netlify. That's what we are going to use here.

(In case you are not interested in Github Actions and want to use Netlify to build your project, take a look at how to use the Next on Netlify Plugin. It directly wraps your Next.js app and doesn't need as much configuration as we are going to explain.)

Let's start by installing our utility:

npm install -D next-on-netlify

Set Next.js target to serverless

We must build our Next.js app as a serverless app. Create a new next.config.js file at the root of your project:

// next.config.js

module.exports = {
  // Target must be serverless
  target: "serverless",
};

Add a post build hook

We need to add a postbuild command that is automatically triggered after our build command finishes. next-on-netlify does a lot of "magic" to copy and set up our Next.js app to be correctly hosted on Netlify.

{
  "name": "next-netlify-github-actions-starter",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "postbuild": "next-on-netlify"
  },
  ...
}

Configure Netlify

Remember the file that was automatically created and called netlify.toml? You can remove all the boilerplate and replace it with only this code (be careful in respecting the indentation):

[build]
  command   = ""
  functions = "out_functions"
  publish   = "out_publish"

Technically, when next-on-netlify will run, it will take what is in these folders and host it on Netlify. DO NOT CHANGE the name of these folders as these are hardcoded into the utility.

Don't forget to add these line to your .gitignore file

# Netlify build
out_*

You can commit your files. Let's work now on the Github Actions configuration.

Github Actions configuration

The netlify configuration is now done, all dependencies installed, it's time to configure our Github actions which will test, build and deploy our Next.js application to Netlify. But before that, we need to set up some Github secrets that we will need in our GH Actions.

Go to your Github project > Settings > Secrets > New repository secret

Actions secret name	Comments
`NETLIFY_AUTH_TOKEN`	Request your token here
`NETLIFY_SITE_ID`	The site to where deploy your site (get it from the API ID on your Site Settings)

Create a new file called main.yml inside .github/workflows. Copy-paste the following code and read the explanation of it after this snippet.

name: Main workflow

on:
  pull_request:
    branches:
      - master
      - main
    types: [opened, synchronize, reopened]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      # Cache node modules and next folder
      - name: 📬 Caching
        uses: actions/cache@v2
        with:
          path: |
            **/node_modules
            ${{ github.workspace }}/.next/cache
          key: ${{ runner.os }}-modules-${{ hashFiles('**/package-lock.json') }}

      - name: Use Node.js 14.x
        uses: actions/setup-node@v1
        with:
          node-version: 14.x

      - name: 🧰 Install dependencies
        run: npm run install

      - name: 📦 Build project
        run: npm run build --if-present

      # - name: 🧹 Run lint
      #   run: npm run lint

      # - name: 🐛 Run tests
      #   run: npm run test

      # Deploy to Netlify with a personalized message
      - name: 🚀 Deploy to Netlify
        id: deploy-netlify
        uses: netlify/actions/cli@master
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
        with:
          args: deploy -m 'v${{ steps.package-version.outputs.current-version}} ・ ${{ github.head_ref }}'

Detailed explanation of the main workflow file

Give a name to your Github action
Choose which type of the event should trigger this action, you can use push instead of pull_request, it's up to you.
Specify on which system this action should be launched, I choose the latest version of Ubuntu (Linux).
Checkout your code
Cache your node modules and the .next/cache folder. When you will first run this action, it will take some time. On the second launch, the action will take the modules that exist in the cache and will then proceed way faster.
Specify the version of Node you want to use, in my case, I choose the most recent version of Node 14th.
Install the dependencies of your project.
Build your project. Remember that after the build, the post-build command will be launch. This is what you should see in the build logs in your Github Action tab:
I added lint and test commands, which I commented. You can use these to trigger ESLint, Jest (even Cypress) or any other plugin that ensures your code doesn't have any issue.
Finally, we trigger the Netlify deployment to deploy our Next.js app to Netlify. 🎉

You may have seen an argument passed to the Netlify deploy:

args: deploy -m '${{ github.head_ref }}'

This will add a message (more specifically your branch name) for each Deploy Preview, a way to keep track of which PR generated which Deploy.

On the same deploy page, you can click on the Deploy Preview and access your app using the preview URL.

A better way would be to use another task to automatically populate your pull request with the log and preview URL. At the end of your file, add this action:

# Publish the inspect and preview link to the PR
- name: 👓 Netlify Preview URL
  uses: unsplash/comment-on-pr@master
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    OUTPUT: "This pull request is being automatically deployed to Netlify.\n\n🔍 Inspect: ${{ steps.deploy-netlify.outputs.NETLIFY_LOGS_URL }}\n✅ Preview: ${{ steps.deploy-netlify.outputs.NETLIFY_URL }}"
  with:
    msg: ${{ env.OUTPUT }}
    check_for_duplicate_msg: false

This will automatically create a comment in your PR.

Summary

If you are still reading this, congrats! You have succeeded in deploying a fully enabled Next.JS application to Netlify using Github Actions!

The next step for you now will be to add some linting rules and tests to ensure that you are sending to Netlify, an app that works perfectly!

Feel free to download or fork the next-netlify-github-actions-starter, open an issue if you find any problem or send me any suggestion to make it better!

Sources:

How to Deploy Next.js Sites to Netlify by Jason Lengstorf
Preview Mode for Next.js now fully supported on Netlify by Cassidy Williams
Announcing one-click install Next.js Build Plugin on Netlify by Cassidy Williams