General

Getting the most out of your project management tool

Published Jan 17, 2024

Updated Jan 17, 2024

6 min read

Getting the most out of your project management tool

There are several project management tools on the market that all aim to help your team gain productivity. Each tool has guiding principles and philosophies for managing projects and structuring your team. These stratagems may only sometimes apply to your team, or your team may evolve and discover new priorities they want to track. In this post, we’ll cover the concepts you should consider when understanding how your team operates and how project management tooling principles can impact your teams. Once you have a tool, we’ll share how you can set it up to align with your team through an example of how we achieved results.

Understanding how your team operates

Does your team run an agile workflow? Are you a waterfall organization? Do you ascribe to Kanban methodologies? Do you take pieces of each of these processes and merge them to allow your teams to organize and operate in a meaningful way? I discuss this topic in more depth in our Engineering Leadership podcast, but these methodologies need to align with the metrics you care about.

As organizational leaders, you need to share what you’re tracking with your teams. These typically include Objectives and Key Results (OKRs) or Key Performance Insights (KPIs) curated for your team’s functional area. Your project management tool could inform some of the metrics you select. For instance, DevOps teams may care about DORA, or customer success teams may need to track the time to resolve customer-facing issues. Development teams may leverage these tools to coordinate the work on efforts to avoid duplication of effort, while others may invest in velocity metrics to inform product teams of capacity. Regardless of what metrics you’re gathering, validating that your tool can provide these metrics is essential.

Tooling Principles

I’ve used various project management software, including Jira, Linear, GitHub Projects, Pivotal Tracker, Asana, and Trello. Each tool is structured slightly differently and has different best practices and approaches. For example, Jira attempts to be the all-in-one tool for organizations giving extreme flexibility in how you set and configure projects. On the other hand, you have tools like Linear that are strongly opinionated and have clear guidance on how to use the tool. When selecting a tool, it’s essential to understand its operating principles and how they relate to your team’s operating habits.

This isn’t to say these tools cannot be adjusted to work for your use cases and needs, but some will be easier to adapt than others for specific situations. It’s important to select tools not only for their user-friendliness but also for their adaptability to your organization’s needs. In some cases, this may lead to your team utilizing multiple tools. Given any budget constraints, this may not be ideal, so as organizational leaders, it is vital to have those discussions with our peers to determine what would benefit our team the most. If a single tool cannot solve all your needs, try to limit each department to a single tool. Given their functional area and KPIs, you can likely manage this situation easily through monthly and quarterly reporting shared with your organization. If your department is using different tools, you will probably need to set up external reporting means to aggregate those sources of truth or find a way to connect these apps. Some of these tools have integrations that allow you to sync them, but I’ve found those setups to be clunky and create more overhead for simple reporting facets you need. Regardless of your decision, you must configure these tools for your organization’s success.

Setting up your tool for success

With our operation practices determined and the tool that makes sense for our team based on principles and experience found, it is time to set up the tool for your team’s success. I will share my setup based on how my team operates to demonstrate what this could look like for you.

As a consultancy, my team tends to operate in a waterfall model, as clients have us coming in for specific projects with defined scopes. However, we demonstrate progress to clients on a weekly or biweekly basis. This means we need a tool to help us plan out several months of work and milestones while allowing us to manage it weekly. Our clients aren’t typically interested in micro-details for these projects but care about the macro level of deliverables against milestones. Given these parameters, our team leverages GitHub Projects for our project management. We like it as the tickets stay close to the code, and we can use GitHub’s built-in functionality to manage most of our needs. This prevents our team from learning multiple tools and allows us to build custom workflows quickly using GitHub Actions as needed.

This is an example of a project we ran. I’ve omitted details for privacy reasons, but we ran weekly iterations on this project. We also tracked priority and sized issues to help us understand what deliverables we could demonstrate each week. This helped our team organize around how much we knew we could complete each iteration and allowed team members to pull in additional work each week, given we prioritized other issues and their size. If they needed another issue on a Friday before the iteration ended, they could pull the next issue assigned to them from the next iteration or backlog, allowing for a continuous flow of work week-over-week. If an iteration was not completed, it gave us the information we needed to understand why the work may not be complete and allowed us to plan better for the next iteration. Screenshot of GitHub Project with 5 iterations and additional metadata for priority and size

This workflow allows our team to focus on the client's needs and operate in a way they have ownership over the work as each team member commits to the work they agree to before it’s brought into an iteration. If we needed milestones, we could also assign those to tasks and track them, leveraging other GitHub built-in features. These are generally the types of things you should look for when setting up a tool for your team.

Conclusion

Project management tools are not just for project managers to dictate work to teams. When aligned with how teams operate and their goals, these tools can help your teams achieve at a higher level. Creating processes that don’t align with your team’s daily function to gather non-priority metrics through tools creates resistance and challenges leading to non-performing teams. Suppose your team is struggling because deliverables are not aligning with business goals and metrics. In that case, this is an excellent opportunity to check your processes and team operations and realign them if you discover they are out of sync.

At This Dot, no single process works for all teams and organizations. We work with our teams and clients to determine what processes align with their objectives and goals. The process described above works great for our team but may not work for your team. However, the principles outlined above can aid you in finding the process that works best for your team. If you need help finding your process, contact us to help your team find their groove.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Dustin Goodman
Engineering Manager with a passion for web and application development. Speaker and writer on work experiences and software development. Dog dad and musician fueled by coffee.
@dustinsgoodman @dustinsgoodman

Ticket Management for a Successful Project Delivery

Introduction It is very common to assume that when a project fails to deliver on time, it is either the client's fault for changing scope during development, or the development team's technical inability to deliver the scoped milestone in time. Even if the above assumption may at times be partly correct, in this article, we will cover techniques and management tricks that are aimed at removing or minimizing the risk of failure. I am a strong believer that the way the project is managed is key to a project's success, no matter its scope-creep or difficulties. This article will focus on a specific area of project management: Ticket Management. The article will cover multiple areas of Ticket Management, from "Project Breakdown", to the definition of MVP, until exploring the very fine art of ticket writing. Disclaimer Before we jump into the main content of the article, I want to clarify that what I am about to share in the article below has helped me for years on multiple projects, but it is not a rule, and things may be adapted and work differently for different people and management styles. Break the Project Down There is no better way to start our little journey into project management technique than by discussing project breakdown. There are multiple videos, books, and posts that cover this topic and mostly all of them will refer to the definition of MVP (minimum viable product) as the starting point and first delivery milestone for a project: > A minimum viable product (MVP) is a version of a product with just enough features to be usable by early customers who can then provide feedback for future product development. > https://en.wikipedia.org/wiki/Minimum_viable_product As a project manager (or a tech lead taking over PM responsibility) you will be asked to work with the client to define the first milestone for a given product. This as defined above, will include the minimum amount of features to make the product "usable". On multiple occasions in my career, the client's expectation of an MVP has included more than a real MVP should. This is normal, since the client always wants to make a good first impression, and removing features may, at times, be seen negatively for the product. As I mentioned at the start, this post is going to focus on what YOU can do to make sure it is delivered successfully, and it will not focus on how to deal with difficult clients as that is outside the scope of this post. You may probably be wondering how, if we are not going to discuss MVP definition, are we going to change MVP delivery? Your MVP May Not Be the Client's MVP Well, this is actually where the magic begins. I call it magic, but as you will read in a few sentences, the method I use is pretty simple, but I can guarantee you to be very effective. The first step that we are going to take is to sit down with our team and define what you really would expect to see in a real barebone MVP. I usually find it simpler to address this by calling it *Alpha*. The idea of this exercise is to start from a very basic workable product, and then add small features to it as you and the team may seem fit as the MVP. > NOTE: Instead of starting from MVP requirements and trying to remove things, start from the basic technical implementation and build it up to the client MVP. The expectation of this exercise is a set of milestones that are smaller than the client MVP. This should not only be achieved by removing features that may not be seen as required (for example a newsletter integration), but also by proposing a basic version of agreed components (eg. Removing complex shadow from a card, or removing animation on client interaction). A reduced scope should also be associated with a quicker delivery. It is important to understand that this MVP does not have to be shared with the client, but should be visible within the team and actively used as the first and more important delivery milestone. The client (and all communication to them), will still work toward the MVP feature set and timeline. But internally, the team is working toward a faster delivery and a smaller feature set. You may be asking yourself, what are the reasons to add extra work on your shoulder and how can this help the delivery of a project? An effective breakup of MVP and Alpha will produce the following results: - It will provide early insight into project delivery: If you fail delivery of Alpha, you will quite probably fail overall MVP. - Reduce the complexity of the first iteration: As we will see later, removing unneeded complexity helps the team to focus. - Remove the stress from the team and you: Working on your deadline helps manage internal team stress and work with them. - Prioritizes what is needed: A successful Alpha delivery will deliver the client's working version very early on, and will also reduce the "consequences of failure". Failsafe for Missing Delivery Before we move forward to the next topic, I want to share a few more words about the "Alpha MVP" and its benefits. We are going to focus on missing deadlines and how the above methods, can act as a failsafe. As we all know, projects never go to plan. Many things can happen in a project that could affect its delivery. This could be a team member being sick, a delay in hardware delivery, a slow client, a change of scope, and more. Knowing that missing q deadline is more possible than actually hitting them due to unforeseen circumstances, it is just expected to create some guardrails to support our project. The first thing that comes to mind is probably adding a buffer to your project, and this is amazing if possible. But as experience shows us, extra time means extra features and scope creep from the client (Of course there are techniques to avoid this, but this blog post is focusing on what you can do without involving the client). I am not proposing anything extra for you to do to ensure you have an emergency exit in case of late delivery. All you need to know has already been shared above in the previous section! I have delivered many projects on time, but I have also failed others. What needs to be learned from the failure is that even if we "missed the full delivery" in many cases, we still went to production and the client was still happy. via GIPHY Defining an MVP that focuses on what is needed and not what is nice to have, not only speeds up development, but it will also mean that the tasks left at the end of the project are just nice to have, and issues that can easily go live after a few days and do not require immediate intervention. Just to provide more context, these are a few examples of things that have "bleed" outside of the project delivery, and the client was ok with it as we were still able to go to production. - Progress bars attached to client scrolling of the page - Renewal emails and cron for an e-commerce website - Complex page transition - Image zooming - Past event page The ones above are just simple tasks that we sometimes add to our tickets, without realizing the complexity and extra time that they may bring. Let's analyze the first point "Progress bar". This was initially expected to be developed as part of the main navbar ticket. As much as the feature seems simple, it takes time to test and develop, so we moved it out and delivered it later in the project. This allowed us to use those extra hours for actual changes to the data that happened right before the deadline. Creating an environment within your team where "saving a couple of hours" is seen as something important at every stage of the project, will eventually help you deliver faster. > Sometimes we think of a simple few hours of saving as superfluous, but it just takes a few of these changes to make a difference between delivery and failure. Write Just a Few Tickets In the previous section, we defined our MVP and Alpha milestones, and it is now time to write the tickets to achieve this delivery. My second suggestion is: Just write enough tickets to fulfil a couple of days of work and no more. As you may be aware, writing a ticket is a complicated matter and it can take quite some time- time that can be very valuable at the start of a project. Let's assume two different scenarios. The first is where the PM will focus on writing all the tickets, and the second is where we just write a few to get the team going and then analyze the key differences. Write All the Tickets This is a very common scenario. The PM has been given a project and asked to start it asap. At this stage, the PM will spend his first few days writing all the tickets that have been defined as the MVP and will share them with the rest of the team. He will probably join an onboarding meeting, but most of his time for the first few days will be in writing tickets. The backlog at the end of this exercise is going to be nice and full and the PM is going to feel ready to start. Write Just a Few Tickets Also in this case, the PM has been asked to task a new project, but instead of writing lots of tickets, the PM will just write enough for a couple of days. The Backlog looks empty with just a few tickets. Many Tickets vs Just a Few I know that you are probably thinking that I am mad to suggest writing fewer tickets, but I suggest you read below and probably even ask your team and you will be surprised about the answers. Let's compare the two above by using a few metrics: PM, Team, and Project. PM Time The first is PM. In the case of many tickets, the PM will have to spend a few hours writing tickets. Want or not, this is a lengthy operation that takes time. I usually take around 5-10 min per ticket to write them well with all the acceptance criteria and links required. So writing 20, 30 or even 50 of them can take days. In the case of a few tickets, the PM will regain valuable hours at the start of the project. This can be spent on many important tasks such as defining MVP, client communication, setting up procedures within the team, and actively spending time with the team to ensure they have a full understanding of the project and the product to be delivered. WIN: Write just a few tickets Team We are now changing perspectives and looking at this from the team side. As we have seen before, we have two possible examples. In the first one, the time will come in the morning, and have an onboarding meeting with the PM. After this meeting, they will have the ability to start a project. The backlog is nice and defined, and they have lots of tickets to work on, so they can put their heads down, and get on with the work. In the second, the PM is going to introduce the project and share a few tickets that they should accomplish within the next couple of days. The PM is going to be actively involved, and can get the team feedback on the tickets. For example, the team may prefer a Figma screenshot instead that the link or the team mentioned that would be nice to define Accessibility requirements within each ticket. Even if you would probably think that active cooperation can be achieved also from the first iteration (lots of tickets), I have learned from experience that this is not always the case. When the team has lots of tickets available, they just go on with the work and do not think of changing things as they are already set. Making fewer tickets forces the PM and the team to cooperate, they will all know what they are working toward and make adjustments very easy. WIN: Write just a few tickets Project In this last point, we are going to analyze the advantages and disadvantages that the above methodology would produce for our project. In the first method, the project is going to be fully scoped. The PM is going to be able to easily track the burndown and see the progress of the project. This can also be useful for the client as it will have clean visibility on its "MVP". In the second scenario, the PM has surely lots of extra work to do to maintain the project. She will have to be able to track projects using her milestones and not tickets, and she will have to fill the communication gap produced by the missing tickets. At this stage, you probably think that having more tickets is going to be better, but here comes the best part. Even if having fewer tickets will require the PM to work harder, it will produce a more flexible environment that can easily adapt and or change. Small changes in the way ticket are written can benefit the team's velocity, defining a small chunk of work help understand velocity and productivity, and having fewer tickets allow the client to change the scope and re-imagine his product without creating many obsolete tickets on the board. I agree that having fewer tickets and a dry backlog can be complicated to manage, but the benefits, in the long run, are massive. WIN: Fewer tickets if managed well! :) > Note: I may have been a little biased in the above comparison :P Conclusion Project Management is an art and it can be accomplished in many different ways. My management technique focuses on flexibility, but most importantly, team engagement. I think the success of every project is not held by the client's ability to stay on course with its initial idea, or by PM micro-managing the team to complete all the tasks to create the perfect burndown. I am a strong believer that the project's success is helped by the team working on it. If they are engaged, and all work together to accomplish the project, the project will have no issue. Please note that I am not saying that, if the team can complete their tickets, the project is going to be a success, but if the team is engaged in all aspects of the project, the project has a big chance of success. If a developer has a forum to help you define the technical flow of MVP, the project will be delivered faster. If a developer has the forum to express his/her idea on different breakdowns and execution of a task, the project will gain speed and momentum. Remember, you are not always able to change the client, but you can change the way you deliver the work to them!...

Jul 21, 2023

11 mins

Project Management

Configure your project with Drizzle for Local & Deployed Databases

Updated April 8, 2024: Thanks to Jassi Bacha for pointing out that the migrate function is not exported from the drizzle-orm/postgres-js/migrator module for Vercel. I've updated the article to reflect the correct import path. It was a fun Friday, and Jason Lengstorf and I both decided to try and use Drizzle on our respective projects. Jason went the SQLite route and wrote an amazing article about how he got his setup working. My approach was a bit different. I started with Vercel's Postgres + Drizzle Next.js Starter and wanted to use PostgreSQL. If you don't know what Drizzle is, it's a type-safe ORM similar to Prisma. My colleague, Dane Grant, wrote a great intro post on it, so go check his article out if you want to learn more about Drizzle. Getting my project off the ground took longer than I expected, especially coming from a starter kit, but I figured it out. This is the article I wish I had at the time to help get this project set up with less friction. I will focus on using local and Vercel PostgreSQL, but this same setup should work with other databases and adapters. I'll make some notes about where those places are. While I did use Next.js here, these setup instructions work on other projects, too. Configuring Drizzle Every project that leverages Drizzle requires a drizzle.config in the root. Because I'm leveraging TypeScript, I named mine drizzle.config.ts, and to secure secrets, I also installed dotenv. My final file appeared as follows: ` The schema field is used to identify where your project's database schema is defined. Mine is in a file called schema.ts but you can split your schema into multiple files and use glob patterns to detect all of them. The out field determines where your migration outputs will be stored. I recommend putting them in a folder in the same directory as your schema to keep all your database-related information together. Additionally, the config requires a driver and dbCredentials.connectionString to be specified so Drizzle knows what APIs to leverage and where your database lives. For the connectionString, I'm using dotenv to store the value in a secret and protect it. The connectionString should be in a valid connection format for your database. For PostgreSQL, this format is postgresql://:@:/. Getting your connection string Now, you may be wondering how to get that connection string. If you're hosting on Vercel using their Postgres offering, you need to go to your Vercel dashboard and select their Postgres option and attach it to your app. This will set environment variables for you that you can pull into your local development environment. This is all covered in their "Getting Started with Vercel Postgres" guide. If you use a different database hosting solution, they'll offer similar instructions for fetching your connection string. However, I wanted a local database to modify and blow away as needed for this project. Out of the box, Drizzle does not offer a database initialization command and I needed something that could be easily and quickly replicated across different machines. For this, I pulled in Docker Compose and set up my docker-compose.yaml as follows: ` The 3 most important values to note here are the values in the environment key and the ports. These are what allowed me to determine my connection key. For this example, it would be: postgresql://postgres:postgres@localhost:5432/my-local-db. With the compose file set, I ran docker-compose up -d to get the container running, which also initializes the database. Now, we can connect and operate on the database as needed. Creating the database connection To make operations in our app, we need to get a database connection instance. I put mine in db/drizzle.ts to keep all my related database files together. My file looks like: ` This is a bit more complicated because we're using 2 different Drizzle adapters depending on our environment. For local development, we're using the generic PostgreSQL adapter, but for production, we're using the Vercel adapter. While these have different initializers, they have the same output interface which is why this works. The same wouldn't be true if you used MySQL locally and PostgreSQL in production. If we chose a RDS or similar PostgreSQL solution, we could use the same postgres adapter in both cases but change the connection string. That's all this file does at the end - detects which environment and uses the chosen adapter. If we go to use this exported instance, it won't be able to find our tables or provide type safety. This is because we haven't created our database tables yet. Creating database tables To get our database tables created, we're going to leverage Drizzle's Migrations. This allows us to create atomic changes to our database as our schema evolves. To accomplish this, we define the schema changes in our schema files as specified in our config. Then we can run npm run drizzle-kit generate:pg (or whatever script runner you use) to generate the migration SQL file that will be located where we specified in our config. You want to check this file into source! By default, Drizzle doesn't allow you to override migration names _yet_ (they're working on it!) so if you want to make your migration file more descriptive, you need to take both of these steps: 1. Rename the migration file. Take note of the old name. 2. Locate _journal.json. It should be in your migration folder in a folder called meta. From here, find the old file name and replace it with the new file name. Now, we need to run the migrations. I had some issues with top-level awaits and tsx like the Drizzle docs recommend, so I had to go a slightly different route and I'm not thrilled about it still. I made a file called migrate.mts that I stored next to my drizzle.ts. In theory, I should have been able to import my drizzle connection instance here and use that, but I ran out of time to figure it out and ended up repeating myself across files. Here's the file: ` Here, I'm connecting to the correct database pending environment then running the drizzle migrate command. For local development, I set my connection pool to max at 1. This probably isn't necessary for this use case, but when connecting to a cluster, this is a recommended best practice from the Drizzle team. For the local case, I also had to close the connection to the db when I was done. For both cases, though, I had to specify the migrations folder location. I could probably DRY this up a bit, but hopefully, the Drizzle team will eliminate this need and use the config to set this value in the future. With the above file set and our schema generated, we can now run npm run tsx db/migrate.mts and our database will have our latest schema. We can now use the db client to fetch and store data in our database. Note: Jason uses the push command here. This is fine for an initial database creation, but it will override tables in the future. The migration path is the recommended pattern for non-destructive database updates. Conclusion Congratulations! We can connect to our database and perform CRUD operations against our tables. We can also use Drizzle Studio to modify and inspect our data. To review, we had to: 1. Setup a local PostgreSQL server via a tool like Docker Compose 2. Configure the database adapter to work in local mode 3. Generate a schema 4. Create a script to execute migrations so our database is aligned with our schema This was my first experience with Drizzle, and I enjoyed its SQL-like interfaces which made it easy to quickly prototype my project. I noticed in their Discord that they're about to have a full-time maintainer so I'm excited to see what their future looks like. I hope you enjoy it too!...

Mar 8, 2024

6 mins

VercelJavaScript

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

Getting the most out of your project management tool

Getting the most out of your project management tool

Understanding how your team operates

Tooling Principles

Setting up your tool for success

Conclusion

Dustin Goodman

You might also like

Ticket Management for a Successful Project Delivery

Configure your project with Drizzle for Local & Deployed Databases

Introduction to Zod for Data Validation

Let's innovate together!

You might also like

Ticket Management for a Successful Project Delivery

Configure your project with Drizzle for Local & Deployed Databases

Introduction to Zod for Data Validation