1. The primary key

A dedicated column that serves as the unique identifier of the record (ideally, a GUID or a consecutive number). Every table — without an exception, and I mean it — must have a separate column that uniquely identifies the record.

It may be tempting to use an existing column (such as email in a user table) as the primary key, but doing so makes it impossible to change a user’s email later on. Avoid this at all costs.

Instead, always use a separate column with a truly unique value and use this column exclusively to build relations and connect records in a database. That way, all other data (such as, for example, email or slug) can always be changed without breaking anything.

2. Foreign keys

Similar to primary keys, foreign keys take care of connecting records and maintaining relationships in a database. These must be always treated as read-only, as they ensure data integrity.

3. Automatically generated values

Many databases use computed values such as timestamps (e.g. created_at). All data that was generated without user input should generally be considered immutable. They usually provide meta information about a record and should be treated differently than user data.

4. Records that are immutable by their nature

Some database models include entirely read-only tables, where new data can be added, but existing data can never be modified. It can only be read. A common use case for this is a document activity log or a login history.

Conclusion

All other (user-entered) data should be mutable — always. It may sound obvious, but it’s not always the case. Of course, there can be exceptions, but 99% of the time, this should be the default.

Suppose I’m using a SaaS where I can create a workspace with my company’s name and slug. In case I ever rebrand from ”Average company” to ”Superior company”, I want to be able to change the name, the slug, the admin user’s email address, and so on. If this is not possible, it’s usually a sign of weak database design (or poor UX).

Thanks for reading. Feel free to follow me on Twitter.

Every line of code you don’t write, you don’t have to maintain.

Every single line of code adds complexity to your software. It needs to be developed. It needs to be tested. It needs to be deployed. It requires maintenance. It can break. It can affect other parts of your software. Whenever you feel the urge to add code, think again. Does it justify the work that’s required? Not only to write it but also to keep it intact.

The real 10x engineers are the ones who delete code instead of adding it.

10x engineers are overrated. I’m not even sure if they’re a real thing. The most valuable engineers are the ones who make software less complex. Either by removing code instead of adding even more or not adding any code at all.

Good code reads like a book.

If you’re reading code in an unknown project and you quickly know and understand what’s going on, then you know you’re dealing with good code. Great code should explain itself — even without comments. Comments can add value at times, but generally speaking, code should also be readable without plenty of comments.

Don’t add code unless deemed necessary.

Writing software is fun. But in real-world projects and products, code should only be added if it’s necessary. Don’t add code just for the sake of it. As stated earlier, every piece of code comes at a cost. If you don’t need it right now, don’t add it. Because if you don’t need it right now, you probably never will.

Coding is thinking.

Coding is thinking — executed. Essentially, a piece of code is just thoughts, written in a form computers can understand. When you sit down to solve a problem, you should already have a rough solution in mind. Great code can’t be produced without thinking clearly and thoroughly. Think, then code.

Good code is as complex as necessary, but as simple as possible.

Building a feature in the most complex way is a red flag. Some programming languages can do fancy things — things that make it especially hard to understand what’s going on. Try to strive for the simplest solution possible. Code gets more complex over time automatically. No need to make it extra complicated in the first place just to show off exotic skills.

The code is the truth.

Computers are great at doing precisely what we tell them to. If something doesn’t work as expected, you have given the computer the wrong instructions by writing false or faulty code. Don’t expect the problem elsewhere. Technically speaking, your code always behaves correctly. It just doesn’t do the right thing (correctly).

The code is the only real documentation.

No matter how well you maintain any kind of documentation of your code, it’s almost guaranteed to be outdated. The actual code is the only real documentation of what’s going on in your software and why/how a feature behaves a certain way. Documentation is good, documentation is necessary. But the code is the single source of truth.

8 hours of thinking, 1 hour of coding > 1 hour of thinking, 8 hours of coding.

It’s stupid to measure the output of a software engineer by hours spent writing actual code. Coding is the final piece of the puzzle. It’s way more important to sit down, think, and come up with the best possible solution for the problem at hand. Focus on solving the problem first, then sit down and write code. Not the other way around.

A programming language is just a tool.

Every programming language has its specialties — it has its strengths, it has its weaknesses. And it has certain areas of application. Different programming languages are suitable for different kinds of platforms and problems. But a programming language can always be learned. It’s most important to master the foundations. If you’re a problem solver and if you’re good at abstract and logical thinking, you can code in any language.

The best code is no code at all.

If you’ve read this far, then this point needs no further explanation. If you skipped everything, go to the top.

To be continued.

Thanks for reading. If you enjoyed this post, feel free to follow me on Twitter.

1. Understand the basics

Let's start with something obvious (but really important). No matter what you do in life, you need to understand the foundations. This is especially true for programming. I know there are people out there copying code from StackOverflow, pasting it into their editor and then wondering why stuff doesn't work. This doesn't make any sense. If you don't fundamentally understand what you're doing, you're gonna have a bad time. Learn how data types, algorithms and data structures work. Get your hands on different types and kinds of programming languages. Make sure to know your tools before jumping into something bigger.

2. Think before you write

As you mature as a software engineer, you probably notice that you tend to spend more time thinking about a problem and its solution than actually sitting down and writing code. That's because coding is thinking. If you think about your problem first and have a solution in mind already, the actual coding part becomes easy. I often like to say that programming languages are a tool. They look different, they work different, they have their strengths and weaknesses. But if you master logical thinking and problem solving, you can use any programming language with a bit of experience.

3. Be consistent

If you've read my blog post on How to design better APIs, you have probably noticed that there is a "Be consistent" section as well. That's intentional. :) I'd argue that consistency is one of the most important factors when writing software. If you follow the same rules across your entire codebase, it's a lot easier for other people to read, follow, and understand your code. Your code becomes more readable, understandable and maintainable. It's also easier for yourself (if you're working on a project alone). Keep your code clean, keep it simple, keep it consistent.

This applies to:

• File naming
• Indentation
• Naming variables
• Naming functions
• Using single/double quotes

❌ Bad

// Different file name styles
// Not all parameters with explicit type
// Odd indentations
// Unnecessary whitespaces
// Mix of single and double quotes
// Different variable naming style
// Different function naming style

// users-Service.ts
const sendEmail = async (mailSubject, body: string) => {
  const mailClient = new EmailClient()

    const response = await   emailClient.sendEmail(mailSubject, body)

  return response.status
}

// orders.ts
let stat = await sendEmail("Thank you for your order",
    'Your package is on the way.')

✅ Good

// users.ts
const sendEmail = async (subject: string, body: string) => {
  const emailClient = new EmailClient()
  const response = await emailClient.sendEmail(subject, body)

  return response.status
}

// orders.ts
const status = await sendEmail('Thank you for your order', 'Your package is on the way.')

4. Separate concerns

You should always advocate for code that has as little side effects and dependencies as possible. Concerns should be clearly separated, certain pieces of code should do one thing and do one thing well. For example, if you're working on a database service, avoid accessing the application state for accessing the current user ID. Instead, add a parameter that lets callers pass this information themselves. That way, consumers clearly understand which parameters are required in order to call a function. Also, the program doesn't depend on other parts of the software and behaves the same, no matter the state.

❌ Bad

// orders.ts
import { store } from 'state'

const getUserOrders = () => {
  // Database call is depending on the shared application state
  // It's hard for consumers to understand this
  // It can have unpleasant side effects and makes it hard to discover problems
  return orders.filter(o => o.userId === store.userId)
}

✅ Good

// orders.ts
const getUserOrders = (userId: string) => {
  // User ID is passed as parameters
  // The function is more "pure" and doesn't depend on other components/state
  return orders.filter(o => o.userId === userId)
}

5. Don't use magic numbers

Magic numbers and strings are bad. They are mostly inline variables that are used for a specific purpose that isn't immediately clear when looking at the code, which makes the code complicated to read and understand. Instead of throwing in a "magic number", extract a variable with a name that clearly indicates the purpose.

❌ Bad

if (users.length >= 100) {
  // Which limit? What does 100 mean?
  console.log('Limit reached')
  return
}

✅ Good

// Add separate variable that clearly indicates what "100" stands for
const earlyAccessUserLimit = 100

if (users.length >= earlyAccessUserLimit) {
  console.log('Early access user limit reached')
  return
}

6. Don't reinvent the wheel

Programming is fun. As engineers, we tend to want to write our own solutions for almost everything, because we love solving problems. It doesn't always make sense though. Try to leverage other frameworks, tools and services and focus on solving your own problem. There is so much great software out there you can use – mostly even free of charge. Go use it! Every line of code you don't write, you don't have to maintain.

7. Use fewer dependencies

Conversely, don't pull in a package or use another provider for everything. If there is a very simple solution to your problem, don't add too much overhead by adding an external dependency. There are literally npm packages that provide one single function. Don't overuse packages. Know when it makes sense to use a third-party service or package instead of writing your own code.

8. Use self-explanatory names

As already mentioned in "Be consistent", it's crucial to use self-explanatory, simple names across your entire codebase. Don't use unnecessary abbreviations. Don't use arbitrary names. Good code reads like a book. It's easy to understand, it's easy to maintain, it's a joy to work with.

This applies to:

• Files
• Functions
• Variables
• Parameters

❌ Bad

// What does this mean?
const maxMbs = 10

// Get orders from where/whom?
const getOrders = (id: string) => {
  ...
}

// Matching what?
const matchingOrders = orders.filter(x => x.status === 'fulfilled')

✅ Good

const fileSizeLimitMb = 10

const getOrdersByUserId = (userId: string) => {
  ...
}

const unfulfilledOrders = orders.filter(o => o.status !== 'fulfilled')

9. Don't over engineer (YAGNI)

In programming, there is a principle called "YAGNI" (You ain't gonna need it), which states that functionality should not be added unless deemed necessary. You should always keep this in mind. Only implement new functionality when you actually need it, not when you think you will need it in the future. Because, most likely, you never will. Also, don't build a feature in the most complex way. Abstraction can be great where it makes sense, but it can also be a real pain if used mindlessly. Remember, every new code needs to be maintained, so it's better to only add code that's actually required. Otherwise it only adds overhead and doesn't bring any value.

10. Avoid duplication/redundancy

There's also a principle called "DRY" (Don't repeat yourself), which states that you should avoid redundancy (don't duplicate code, have a single source of truth) at all costs. This holds true for code, data and comments.

• Don't copy or duplicate code
• Don't store data redundantly
• Don't add comments that don't add context

It's better to write clean, reasonable code and refrain from comments rather than writing less readable code and adding comments. Also, code duplication is one of the worst things you can do. Whenever you need to reuse a piece of code, extract it into a separate file/module/function depending on the language you're using.

11. Refactor if necessary

Don't be afraid of refactoring your code if there is a necessity. Software evolves, and so should you. It's better to get rid of a technical debt and refactor that piece of code instead of carrying it along and grit your teeth on it. Every now and then, take some time to go through your code and take the time to refactor and make it better instead of adding another feature. It's worth it in the long run.

12. Don't make assumptions

You shouldn't make any assumptions about how your code will behave in certain situations. Even though you think your code can never enter state X, it doesn't mean that it won't. Handle errors. Expect the unexpected. Make sure your code runs, no matter the state or outcome. This is especially important for user inputs – you can never know what kind of data a user will enter. I often like to apply Murphy's law in this context – anything that can go wrong will go wrong at some point.

13. Take advantage of immutability

Whenever possible (and reasonable), try to use immutable data types and avoid manipulating existing variables directly. It might seem cumbersome first, but your code becomes way more predictable and less error-prone if you work with immutable objects. Changing existing variables directly can have unintended, hard to find side effects, which you should avoid if necessary. You literally protect yourself from making dumb mistakes.

14. Introduce environment variables

Always introduce environment variables for data that shouldn't be hard-coded into your software. For example, database connection strings, file system paths and app preferences. Never store data like this directly in your code. It's a lot better to inject information from outside – that way, you keep everything in one place, can make changes quickly, and most importantly, don't expose confidential in your source code.

15. Get in the zone

Programming requires concentration, it requires focus. When you tackle a problem, make sure to get in the zone. Silence notifications. Think into the problem and its possible solutions. If your mind is not free, you will find yourself jumping around, not being concentrated and thus, not getting anything done. Get in the zone, and don't break the flow.

If you enjoyed this post, feel free to follow me on Twitter.

1. Learn every day

The only constant is change. Most people think that they‘re done learning once they finish school or education. Wrong. By the time you‘ve finished school, you probably don‘t know much. You‘re only getting started there. It‘s important to know that you should learn every day and that you can learn from everyone. Develop a new skill, satisfy your curiosity, and try something completely different. Learning is fun and can get you anywhere. Never stop learning.

2. Help as much as you can

I‘ve always been convinced that helping others and sharing knowledge without expecting anything in return is a positive-sum game. But only since I started blogging last year, I‘ve experienced this in practice. My post on How to design better APIs recently hit 150k views. It resonated with many people and was genuinely helpful to a lot of folks. Knowing that something you‘ve created is valuable and helpful to others is an incredible feeling. I think that everyone can and should create more things.

3. Take ownership

I‘ve made it a habit to publicly acknowledge my own mistakes. If something goes wrong, you should always take full responsibility for it. You shouldn‘t blame it on anyone else. Explain what went wrong, why it happened, and how it will never happen again. By the end of the day, it‘s more important to be high integrity and honest instead of making up some random excuse and blaming it on someone else. Customers will forgive you. They will appreciate and value your openness. That way, they can verify that you‘re a trustworthy and long-term partner.

4. Give credit

Similarly, if someone else does something great, give credit to them. Say „thank you“, „nicely done“, or „I couldn‘t have made it without you“. It‘s extremely powerful to actively show a team member, business partner, or customer your appreciation. It makes them feel valued and appreciated. Their work is important and should be treated that way. Never underestimate the effect of saying something nice.

5. Don‘t take it personally

This is something I need to work on myself. I‘m extremely proud of my work and I don‘t want to make any mistakes. Consequently, I quickly take things personally, which is unnecessary. If a customer is – for example – angry because of some nasty bug in their software, they‘re angry because of that bug, not because they consider you an idiot. It‘s important to differentiate yourself from your company, especially if you‘re working alone. Focus on fixing the problem instead of feeling attacked.

6. Celebrate your achievements

In our fast-moving world – particularly in the software industry – it’s easy to lose track of your achievements and successes. Milestone after milestone, it often happens that victories are not properly celebrated. It shouldn‘t be that way. Once you publish that first version of an app, take a break, get a cold drink, have a nice dinner, and celebrate. If you don‘t celebrate your achievements yourself, why should anyone else? Consciously taking time to celebrate is important to get new energy and stay motivated.

7. Learn from your mistakes

Failing is not a shame. It’s one of the most important factors to grow – both personally and as a business. No matter how hard you fail, there’s always an upside. You just have to see it. Find that positive side, accept it, and draw your lessons from it. Failure is natural. Failure is OK. Not getting better with every failure you make is not.

8. Don‘t get lost in details

There‘s a saying. Make it work, make it fast, make it beautiful. The order is important. Whatever you do, don‘t lose yourself in tiny details early on. It‘s more important to ship a working feature that delivers value to a customer rather than building it in the most beautiful way. Focus, get in the zone and don‘t go in circles. Execution is everything.

9. Say „no“ more often

People generally want to be nice and don‘t want to hurt their counterparts. It‘s therefore often hard to say NO. But it‘s important. Always saying yes to everything makes you prone to being exploited by people. Also, it‘s irrational to accept and do everything that‘s expected from you. You‘re an individual human and you have the right to do things your way.

10. Don‘t make promises you can‘t keep

It‘s tough to let someone down by saying „no“. But it‘s even worse to make promises you can‘t keep. Be honest, say the truth, and only do realistic things. It‘s better to decline something up front instead of being sorry later on.

11. Make your own decisions

It‘s great to listen to people and get their feedback and opinions. Feedback can be really valuable. But be careful who you get feedback from. Most people care about themselves and act according to their interests. Use your judgment. Listen to yourself. By the end of the day, you must make your own decisions and live with them.

12. Don‘t define yourself solely by work

People are multivariate. You are not exclusively your company. Of course – if you‘re working on your startup, work will take up a big part of your life. But that doesn‘t mean there‘s nothing else. You still have hobbies, you have interests, and you have other opinions. There are people out there that value you for things other than your MRR or your startup‘s valuation. Don‘t couple your personality too tightly to your business.

13. Don‘t chase arbitrary things

Live in the here and now. Most people choose to be unhappy until something arbitrary happens. Don‘t chase an arbitrary 1 million dollars. Don‘t wait until you‘re 30. Don‘t wait for that special day to come. It probably never will. Be the person you always wanted to be and do the things you always wanted to do, now. Just do it.

14. Watch yourself

You are busy building your startup. I get that. Everyone is. I am so too. But while you‘re working hard, you shouldn‘t do so to a detriment of your health. Slow down. Take some time off. Take care of your body. Take care of your mind. Be happy. Be healthy. Nothing else matters.

15. Don‘t take it too seriously

Life is short. Your lifetime is limited (I know, it sucks). Don‘t take yourself so seriously. It doesn‘t always have to be hard. Laugh about yourself. Have fun. Do some crazy stuff. Make it count. ✌️

Vue 3 has officially been released on 18 September 2020, and as of 7 February 2022, it‘s now the default version. So when I started working on a new app in autumn 2021, an app which I knew would exist for many years, I thought it would be a good idea to start with Vue 3 right away. But since Vue 3 brings quite some changes — most notably, the Composition API — I had been very hesitant to make the switch. Especially, because my beloved scaffold project had worked so well.

But kicking off a large project with an old framework doesn‘t make any sense, so I needed to figure out a way to get started with Vue 3. I struggled a bit to get into the „flow“ of building clean, maintainable and robust components first, but I think I found a way that I probably like even more than the Vue 2.x class component way. So in this post, I want to share my opinionated approach to work with Vue 3. An approach, that will hopefully help you building better Vue components. We will create a component step-by-step, explaining all the decisions we make in detail. But first, let‘s get started with some fundamental things.

1. TypeScript

Starting with Vue 3, TypeScript is now a first-class citizen of the framework (Vue 3 is written in TypeScript itself). For that reason, it's especially easy to use TypeScript in your Vue 3 projects. I had been using TypeScript in Vue 2 already, and starting with Vue 3, it makes even more sense. Use Vue with TypeScript, your entire codebase becomes type-safe and it will save you from a lot of troubles.

2. Composition API

As mentioned before, the Composition API is probably the most important concept to understand in comparison to Vue 2. In Vue 2, we only had the Options API (where we define data, props, methods, and so on in our components), where in Vue 3, we also have the more flexible Composition API, that exposes reactive data and logic, which can be reused in other components as well.

I‘d argue that it generally makes sense to use the Composition API for new Vue 3 projects, as it‘s a lot more versatile and allows for easier sharing of logic and data. In fact, I haven‘t written an Options API-style component in Vue 3 yet, but we‘re getting there. ✌️

3. Syntax

Now that we‘ve committed ourselves to prefer the Composition API over the Options API, we need to choose one of the syntax styles that are supported to create Composition API components.

❌ Option 1 — Component (example from the official Vue.js documentation)

The first option is to export a default component and expose reactive data using the setup method. When I first saw this, I thought that it was very verbose. Luckily, there‘s a better way — but let's see the conventional syntax first.

<script>
import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)

    return {
      count
    }
  }

  mounted() {
    console.log(this.count) // 0
  }
}
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>

✅ Option 2 — script setup

The second option is to use the script setup syntax, which has a couple of benefits (less verbose, exposure of top level bindings, better TypeScript support, … I will explain them in detail as we proceed). So this is what we‘re going to use.

<script setup>
import { ref } from 'vue'

const count = ref(0)
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>

If you compare the script setup syntax with the component syntax, you can instantly see a huge difference. It's a lot more clean and concise, and is generally preferred over the "default" component approach, because of its better TypeScript support, performance, and ease of use.

4. Putting it together

So if we combine the use of TypeScript and the Composition API (using the script setup syntax), we get the following boilerplate code for our Vue 3 components. It's important to use the lang="ts" attribute so that strict type checking is enabled.

<script setup lang="ts">
</script>

<template>
</template>

Quite little code, isn't it? I really value the beauty and simplicity of writing components like this. Compared to the class component approach in Vue 2, there is practically no overhead required to bootstrap new components.

5. Custom button component

Let's build our first custom MagicButton component in Vue 3. We will add more functionality to the component step-by-step, which I will explain in detail.

Our initial draft renders a default HTML button element with the text "Click me", but doesn't provide any options to pass props or receive events.

// MagicButton.vue

<script setup lang="ts">
</script>

<template>
  <button>Click me</button>
</template>

Props

We want to accept a text that the button should display. Therefore, we first add a Props interface to the component, which defines the shape of the props that can be passed. We then call defineProps<Props>() to expose our props.

// MagicButton.vue

<script setup lang="ts">
+ interface Props {
+  text: string
+ }

+ defineProps<Props>()
</script>

<template>
+  <button>{{ text }}</button>
</template>

Like that, we are able to import the component and use it as follows.

// Home.vue

<script setup lang="ts">
import MagicButton from './components/MagicButton.vue'
</script>

<template>
  <MagicButton text="Login" />
</template>

Default values

We want to be able to set the loading state of the button, which should be an optional property. Therefore, we add another prop called loading, which accepts a boolean value. Since we don't want to explicitly set this prop, we use the withDefaults compiler macro to define a default value. That way, the compiler knows that this property is optional and won't warn us when not setting it. We also set the button state to disabled if loading is true and show a different text in that case.

// MagicButton.vue

<script setup lang="ts">
interface Props {
  text: string
+ loading: boolean
}

+ withDefaults(defineProps<Props>(), {
+  loading: false
+ })
</script>

<template>
+  <button :disabled="loading">
+    <span v-if="loading">Loading...</span>
+    <span v-else>{{ text }}</span>
   </button>
</template>

Emits

We also want to get an event when the button is actually clicked. We therefore define emits using the defineEmits compiler macro. Whenever the button is clicked, we call the click event, passing the actual click event payload.

// MagicButton.vue

<script setup lang="ts">
interface Props {
  text: string
  loading: boolean
}

withDefaults(defineProps<Props>(), {
  loading: false
})

+ const emit = defineEmits<{
+  (event: 'click', mouseEvent: MouseEvent): void
+ }>()
</script>

<template>
+  <button @click="(event) => emit('click', event)" :disabled="loading">
     <span v-if="loading">Loading...</span>
     <span v-else>{{ text }}</span>
   </button>
</template>

Wrapping up

So we created a custom <MagicButton> component and added support to accept props (including default values) using defineProps and withDefaults, and emit events using defineEmits — all in a type-safe manner! That's pretty neat. We can now use our custom component as follows.

// Home.vue

<script setup lang="ts">
import MagicButton from './components/MagicButton.vue'

const click = (event: MouseEvent) => {
  console.log('click', event)
}
</script>

<template>
  <MagicButton loading text="Login" @click="click" />
</template>

6. Custom input component

Let's build a second custom component called MagicInput. In this component, we will use a custom v-model expression, call functions within our component, as well as introduce reactivity using ref and computed. Again, we start with the most basic setup, rendering only a default HTML input element.

// MagicInput.vue

<script setup lang="ts">
</script>

<template>
  <input type="text" />
</template>

Two-way binding

To use two-way binding with v-model in a custom component, we can use the modelValue prop and the update:modelValue emit accordingly.

// MagicInput.vue

<script setup lang="ts">
+ interface Props {
+   modelValue: string
+ }

+ defineProps<Props>()

+ const emit = defineEmits<{
+  (event: 'update:modelValue', value: string): void
+ }>()
}
</script>

<template>
+ <input :value="modelValue" @input="emit('update:modelValue', $event.target.value)" type="text" />
</template>

We can then use the v-model expression on our custom component to two-way bind the text.

// Home.vue

<script setup lang="ts">
import { ref } from 'vue'
import MagicInput from './components/MagicInput.vue'

const text = ref('')
</script>

<template>
  <MagicInput v-model="text" />
</template>

ref and computed

To get a bit more into detail on what the Composition API offers us, we are now going to add some reactivity using ref and computed. We therefore get rid of the two-way binding and instead, accept only an initial value and use an internal ref that handles input changes.

// MagicInput.vue

<script setup lang="ts">
+ import { ref } from 'vue'

interface Props {
- modelValue: string
+ initialValue: string
}

const props = defineProps<Props>()

// Introduce a ref and pass the initalValue prop as the initial value
+ const text = ref(props.initialValue)

- const emit = defineEmits<{
-  (event: 'update:modelValue', value: string): void
- }>()
}
</script>

<template>
  <input v-model="text" type="text" />
</template>

So far so good, we now have a reactive ref variable that is bound to the input using the v-model expression. That way, the variable always reflects the current value of the input. Now, let's add a computed property that displays the length of the current text.

// MagicInput.vue

<script setup lang="ts">
- import { ref } from 'vue'
+ import { ref, computed } from 'vue'

interface Props {
  initialValue: string
}

const props = defineProps<Props>()

const text = ref(props.initialValue)
+ const textLength = computed(() => text.value.length)
</script>

<template>
  <input v-model="text" type="text" />
+ <p>Your text is {{ textLength }} characters long.</p>
</template>

So now we can use the textLength computed property that always returns the current length of the text. Please note that, because text is a ref, we need to call .value (e.g. text.value.length) to get the actual value of the property.

Functions

Most of the time, we also want to execute some kind of logic within our components, that's why we'll add a function that logs the current text of the input to the console whenever it changes. Since all top-level bindings are exposed to our template, it's as easy as adding a default TypeScript function.

// MagicInput.vue

<script setup lang="ts">
import { ref, computed } from 'vue'

interface Props {
  initialValue: string
}

const props = defineProps<Props>()

const text = ref(props.initialValue)
const textLength = computed(() => text.value.length)

+ const logText = (text: string) => {
+  console.log(`The current text is ${text}`)
+ }
</script>

<template>
+ <input 
+   v-model="text"
+   @input="logText($event.target.value)"
+   type="text"
+ />
  <p>Your text is {{ textLength }} characters long.</p>
</template>

Wrapping up (again)

This time, we created a custom <MagicInput> component that allows us to use v-model, leverage reactivity using ref and computed and also execute custom logic. We can now use our custom component as follows.

// Home.vue

<script setup lang="ts">
import { ref } from 'vue'
import MagicInput from './components/MagicInput.vue'

const text = ref('Ronald Blüthl')
</script>

<template>
  <!-- First version using v-model -->
  <MagicInput v-model="text" />

  <!-- Second version using initial value -->
  <MagicInput initial-value="Ronald Blüthl" />
</template>

7. Summary

We built two minimalistic components, MagicButton and MagicInput, that cover probably 95% of the functionality that is typically needed when creating custom components.

• Using TypeScript to enjoy full type safety for all our components
• script setup to make use of the Composition API in a very convenient way
• defineProps and withDefaults for props and default values
• defineEmits for emits (events)
• v-model for two-way binding
• ref for reactive data
• computed for reactive read-only data

Using these few techniques, we're able to pass data to a component, receive data from a component, bind values in both ways and create reactive state and logic.

8. General considerations

In Vue, there are sometimes many ways to achieve the desired result. I usually try to be as consistent as possible, that's why I make sure to follow these rules (most of which are suggested in the Vue documentation as well).

Naming and casing

• Use PascalCase for components (<MagicButton>, <MagicInput>)
• Use kebab-case for props (initial-value, loading) — except modelValue

Best practices

• Use single quotes instead of double quotes
• Infer the data type if obvious (const text = ref('Ronald')) instead of (const text = ref<string>('Ronald'))
• Define the data type if it must be explicit (e.g. const text = ref<string | null>(null))
• Don‘t use semicolons (they are not necessary and improve readability)
• Always extract a Props interface instead of defining an inline object
• Prefer initial-value="Ronald Blüthl" over :initial-value="'Ronald Blüthl'" when NOT passing a variable
• Prefer loading over :loading="true" when passing boolean props
• Avoid watch expressions as much as possible (they are really hard to debug)

One-way data flow

Data flows into one way only in Vue. If the parent data updates, the child data is updated as well, but not the other way around. This means, that props are read-only. If you want to mutate passed props, use a ref and pass the prop value as the initial value, for example:

interface Props {
  initialText: string
}

const props = defineProps<Props>()
const text = ref(props.initialText)

Don't mutate objects and arrays

Because of the nature of JavaScript objects and arrays, it is technically possible to mutate them in a component, which then also affects the parent component. You should always avoid this, as it becomes extremely hard to discover problems in your data flow later on. Instead, emit an event with the updated data and let the parent component perform the mutation, for example:

const props = defineProps<{
  names: string[]
}>

const emit = defineEmits<{
  (event: 'change', names: string[]): void
}>()

const addName = (name: string) => {
  const updatedNames = [...props.names, name]
  emit('change', updatedNames)
}

9. Final words

So this is my practical approach to building Vue 3 components, which I used for many projects in the last couple of months. As mentioned at the beginning of the article, I've been using Vue for many years already, and I think that it really grew as a framework. The combination of using the Composition API with TypeScript and script setup is a really nice way to write clean and concise components in Vue 3. It works very well for me, and I hope it does for you too.

If you have any questions, just let me know in the comments below. If you found this post useful, feel free to follow me on Twitter, as I document my journey as an indie hacker there. My DMs are open (I'm always happy to help). 🙌

I created "reference implementation" based on my recent post on How to design better APIs. I tried my best to practically implement all tips mentioned in the article. It's built with Next.js. Check it out here.

Walk-through Video

Preface

On March 3rd 2022, I published an article on How to design better APIs on my Hashnode blog. For some reason, it got quite popular — by the time of writing this, it has over 325 reactions, 34 comments (including my answers) and 112k+ views. It even made it to the front page of Hacker News on March 12th, which is kind of a big deal for me.

What I’m even more happy about, however, is that so many people reached out to me, said that the post was helpful and that it really provided value to them. I appreciate that a lot and I’ll do my best to continue creating useful content in the future, so thank you for reading this. 🙂

Since the tips mentioned in the post were meant to be „language-agnostic“, a couple of folks also asked if there is a project where they can look up an actual real-world implementation. That’s when I thought it would be a nice idea to complement the blog post with an actual project where most of the tips are applied in practice. So here it is! The API is, of course, overly simplistic (no database, no real authentication), but you should get an idea of all the concepts.

How does it work?

The project is built with Next.js API Routes and TypeScript. I created one /users resource and tried to compress all 15 tips (including pagination, error handling, ...) into a few routes. You can have a look at the repository and the entire source code on my GitHub account. Clone it here. If you have any questions, just shoot me a DM on Twitter. I'm always happy to help and discuss.

The project is basically structured like this:

• pages/api/v1* — The API
• models/* — Request and response types
• services/* — Fake data services

In order to keep everything focused on the API itself, I didn't use a real database. Instead, I "faked" the data access logic and used services that return test data.

Following, I will repeat the original blog post's tips and add detailed information on how they're implemented. You can click most of the headers and jump right into the code on GitHub.

There is also a Postman collection checked into the project, where you can play with all API routes.

1. Be consistent

I use the same naming conventions, resource names, HTTP methods and status codes across the entire project.

• snake_case naming in requests and responses
• POST for creating
• GET for reading
• PATCH for updating
• DELETE for deleting
• 200 for success
• 201 for creation
• 400 for client errors
• 401 for unauthorized
• 404 for not found
• 405 for method not allowed

2. Use ISO 8601 UTC dates

I use ISO 8601 UTC dates (more precisely, the specific RFC 3339 format, providing date and time).

  const now = new Date()
  return {
    id,
    name,
    email,
    created_at: now.toISOString(),
    modified_at: now.toISOString()
  }

3. Make an exception for public endpoints

I added a middleware that requires an API key to be present for each API route.

import { NextResponse, NextRequest } from 'next/server'
import { unauthorized } from 'models/error'

export async function middleware(req: NextRequest, res: NextResponse) {
  const { pathname } = req.nextUrl

  if (pathname.startsWith('/api') && !req.headers.get('Api-Key')) {
    return new Response(JSON.stringify(unauthorized), {
      status: 401, headers: {
        'Content-Type': 'application/json'
      }
    })
  }

  return NextResponse.next()
}

4. Provide a health check endpoint

I added a GET /api/v1/status endpoint that always returns 200.

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  // GET /api/v1/status
  if (req.method === 'GET') {
    res.status(200).end()
  }

  res.status(405).end()
}

5. Version the API

All API routes live inside the v1 folder, which automatically adds the /v1 version to every resource within that folder. I also added a /v2 version of the status endpoint to give you an idea on how another version would look like.

6. Accept API key authentication

The middleware is used to determine the presence of an Api-Key HTTP header which could then be used to fetch an account with the given API key from the database. In our case, we only check whether this header is provided, otherwise the API will return a 401.

7. Use reasonable HTTP status codes

I'm using a very small set of HTTP status codes (200, 201, 400, 401, 404, 405). See #1 for details.

8. Use reasonable HTTP methods

I'm using a very small set of HTTP methods (POST, GET, PATCH, DELETE). See #1 for details.

9. Use self-explanatory, simple names

All endpoints and names are self-explanatory.

• POST /users
• GET /users
• GET /users/{id}
• PATCH /users/{id}
• DELETE /users/{id}

10. Use standardized error responses

I added an error response type that is always used when something wrong happens (4xx).

export type Error = {
  code: string
  message: string
}

11. Return created resources upon POST

After a resource is created, the most recent "snapshot" of that object is returned from the API.

12. Prefer PATCH over PUT

I don't use any PUT requests. Updates are always designed around PATCH.

13. Be as specific as possible

All endpoints are limited to the essentials and don't do anything unexpected.

14. Use pagination

I added a Paged type that wraps GET requests into a standardized paginated response.

15. Allow expanding resources

It's possible to load orders when fetching users using the expand query parameter.

In this post, I'm trying my best to compress everything I know about what makes a good API. An API, that your consumers will enjoy using. All tips are language-agnostic, so they apply to any framework or technology.

1. Be consistent

I know it sounds logical, but it's hard to get this one right. The best APIs I know are predictable. When a consumer uses and understands one endpoint, they can expect that another endpoint works the same way. This is important for the entire API and one of the key indicators of whether or not an API is well-designed and great to use.

• Use the same casing for fields, resources, and parameters (I prefer snake_case)
• Use either plural or singular resource names (I prefer plural)
  • /users/{id}, /orders/{id} or /user/{id}, /order/{id}
• Use the same authentication and authorization methods for all endpoints
• Use the same HTTP headers across the API
  • For example Api-Key for passing an API key
• Use the same HTTP status codes based on the type of response
  • For example 404 when a resource can not be found
• Use the same HTTP methods for the same kind of actions
  • For example DELETE when deleting a resource

2. Use ISO 8601 UTC dates

When dealing with date and time, APIs should always return ISO 8601-formatted strings. Displaying dates in a specific time zone is generally a concern of client applications.

{
    "published_at": "2022-03-03T21:59:08Z"
}

3. Make an exception for public endpoints

Every endpoint should require authorization by default. Most endpoints require an authenticated user to be called, so making this the default makes sense. If an endpoint needs to be called publicly, explicitly set this endpoint to allow unauthorized requests.

4. Provide a health check endpoint

Provide an endpoint (for example GET /health) that determines whether or not a service is healthy. This endpoint can be called by other applications such as load balancers to act in case of a service outage.

5. Version the API

Make sure you version your API and pass the version on each request so that consumers aren't affected by any changes to another version. API versions can be passed using HTTP headers or query/path parameters. Even the first version of the API (1.0) should be explicitly versioned.

Some examples:

• https://api.averagecompany.com/v1/health
• https://api.averagecompany.com/health?api_version=1.0

6. Accept API key authentication

If an API needs to be called by a third party, it makes sense to allow authentication via API keys. API keys should be passed using a custom HTTP header (such as Api-Key). They should have an expiration date, and it must be possible to revoke active keys so that they can be invalidated in case they get compromised. Avoid checking API keys into source control (use environment variables instead).

7. Use reasonable HTTP status codes

Use conventional HTTP status codes to indicate the success or failure of a request. Don't use too many, and use the same status codes for the same outcomes across the API. Some examples:

• 200 for general success
• 201 for successful creation
• 400 for bad requests from the client
• 401 for unauthorized requests
• 403 for missing permissions
• 404 for missing resources
• 429 for too many requests
• 5xx for internal errors (these should be avoided at all costs)

8. Use reasonable HTTP methods

There are many HTTP methods, but the most important ones are:

• POST for creating resources
  • POST /users
• GET for reading resources (both single resources and collections)
  • GET /users
  • GET /users/{id}
• PATCH for applying partial updates to a resource
  • PATCH /users/{id}
• PUT for applying full updates to a resource (replaces the current resource)
  • PUT /users/{id}
• DELETE for deleting resources
  • DELETE /users/{id}

9. Use self-explanatory, simple names

Most endpoints are resource-oriented and should be named that way. Don't add unnecessary information that can be inferred from elsewhere. This also applies to field names.

✅ GOOD

• GET /users => Retrieve users
• DELETE /users/{id} => Delete a user
• POST /users/{id}/notifications => Create a notification for a specific user
• user.first_name
• order.number

❌ BAD

• GET /getUser
• POST /updateUser
• POST /notification/user
• order.ordernumber
• user.firstName

10. Use standardized error responses

Aside from using HTTP status codes that indicate the outcome of the request (success or error), when returning errors, always use a standardized error response that includes more detailed information on what went wrong. Consumers can always expect the same structure and act accordingly.

// Request => GET /users/4TL011ax

// Response <= 404 Not Found
{
    "code": "user/not_found",
    "message": "A user with the ID 4TL011ax could not be found."
}

// Request => POST /users
{
    "name": "John Doe"
}

// Response <= 400 Bad Request
{
    "code": "user/email_required",
    "message": "The parameter [email] is required."
}

11. Return created resources upon POST

It's a good idea to return the created resource after creating it with a POST request. That's mostly important because the returned, created resource will reflect the current state of the underlying data source and will contain more recent information (such as a generated ID).

// Request: POST /users
{
    "email": "jdoe@averagecompany.com",
    "name": "John Doe"
}

// Response
{
    "id": "T9hoBuuTL4",
    "email": "jdoe@averagecompany.com",
    "name": "John Doe"
}

12. Prefer PATCH over PUT

As mentioned earlier, PATCH requests should apply partial updates to a resource, whereas PUT replaces an existing resource entirely. It's usually a good idea to design updates around PATCH requests, because:

• When using PUT to update only a subset of fields for a resource, the entire resource still needs to be passed, which makes it more network-intensive and error-prone
• It's also quite dangerous to allow any field to be updated without any restrictions
• From my experience, there barely exist any use cases in practice where a full update on a resource would make sense
• Imagine an order resource that has an id and a state
• It would be very dangerous to allow consumers to update the state of an order
• A state change would much more likely be triggered by another endpoint (such as /orders/{id}/fulfill)

13. Be as specific as possible

As outlined in the previous section, it's generally a good idea to be as specific as possible when designing endpoints, naming fields, and deciding which requests and responses to accept. If a PATCH request only accepts two fields (name and description), there is no danger of using it incorrectly and corrupting data.

14. Use pagination

Paginate all requests that return a collection of resources and use the same response structure. Use page_number and page_size (or similar) to control which chunk you want to retrieve.

// Request => GET /users?page_number=1&page_size=15

// Response <= 200 OK
{
    "page_number": 1,
    "page_size": 15,
    "count": 378,
    "data": [
        // resources
    ],
    "total_pages": 26,
    "has_previous_page": true,
    "has_next_page": true
}

15. Allow expanding resources

Allow consumers to load related data using a query parameter called expand (or similar). This is especially useful to avoid round-trips and load all data that is necessary for a specific action in one go.

// Request => GET /users/T9hoBuuTL4?expand=orders&expand=orders.items

// Response <= 200 OK
{
  "id": "T9hoBuuTL4",
  "email": "jdoe@averagecompany.com",
  "name": "John Doe",
  "orders": [
    {
      "id": "Hy3SSXU1PF",
      "items": [
        {
          "name": "API course"
        },
        {
          "name": "iPhone 13"
        }
      ]
    },
    {
      "id": "bx1zKmJLI6",
      "items": [
        {
          "name": "SaaS subscription"
        }
      ]
    }
  ]
}

If you enjoyed this post, feel free to follow me on Twitter.

A good friend of mine, Norbert, moved to the United States a few years ago. Since I still live in Austria, we don't see each other very often. For that reason, we've made it a habit to meet once a year - somewhere in the world. This summer, we went to Ecuador. And quite accidentally, we built an app together...

Norbert and I met somewhere around 2011-2012 at a company where I was doing my apprenticeship at that time. We've been software engineers for all our careers and over the years, we've worked on many projects together - most of which didn't end up anywhere.

Ecuador 2021

In the meantime, we both work as freelance software engineers - giving us the flexibility to work from anywhere at any time. When we flew to Ecuador this year, we were actually planning on working on our ongoing projects during the week, having dinner/drinks at night and visiting some cool places in our spare time. Well, things turned out a bit differently.

Instead of going out for drinks, we decided to do an entire rewrite of AutoForward SMS, an app that Norbert acquired on Flippa earlier this year. (If you're interested in the full story, you should definitely read this post on Indie Hackers).

The app's functionality? Forwarding text messages (SMS) to an E-Mail or URL based on a user defined ruleset. Norbert had told me about the acquisition and his intention to rewrite the app before, but there were no concrete plans until our get-together in Quito.

After several conversations, we spontaneously decided to partner up and start rebuilding AutoForward SMS immediately while we were together. So while we were putting in the ours at our client projects, we were diligently drafting, designing and developing the new app every free minute.

The App

Why Rewrite?

When Norbert took over AutoForward SMS in early 2021, it became clear very quickly that the tech stack was fairly outdated, the code base was in poor condition and the UI/UX could be largely improved. Also, the app should become more scalable, reliable and generally be prepared for future growth - something that couldn't be done very easily.

The New Tech Stack's Premise

For the reasons mentioned above, the new tech stack needed to meet some criteria:

• Cloud-native, serverless architecture
• Cross-platform mobile app framework
• Minimalistic admin UI to manage users/subscriptions
• Generally lightweight and straightforward technology, no overhead

Considering our skillsets and existing knowledge, we then went with the following technologies:

• Firebase Cloud Functions — Backend
• Firebase Firestore — Database
• Flutter — Mobile App
• Vue & Tailwind — Admin UI
• WordPress — Website

The Result

We dedicated our entire workcation pushing the app forward and we actually managed to develop a large chunk of the entire new product (App, Backend, Admin UI, Website) in less than two weeks. When we parted ways at the end of August, we were 80% done and decided to continue working on the remaining 20% remotely.

And so far, everything worked out really well. By the time of writing this blog post, we have already deployed and rolled out the new product to our customers. Our new tech stack is rock-solid and just a joy to work with, both in terms of simplicity and stability.

We challenged ourselves to develop a solid product in a really short time period whilst working on other time-consuming projects, which turned out to work really well. When you commit yourself to a fun project with a good friend, there are literally no limits.

What's Next?

Now that we have successfully made the transition to the new product, we have a lot of work to do at marketing the product, bringing it into the Google Play Store and generally polishing and improving the App. Our target is to attract new customers and making AutoForward SMS the #1 solution for forwarding text messages.

If you enjoyed this post, you can follow my journey on Twitter.