Introduction
The release of Vue 3 ushered in a transformational change, moving from the Options API to the Composition API. At the heart of this transition lies the concept of “composables” — modular functions that utilize Vue’s reactive features. This change has injected greater flexibility and code reusability into the framework. However, it has also birthed challenges, notably the inconsistent implementation of composables across projects, which often results in convoluted and hard-to-maintain codebases.
This style guide aims to harmonize coding practices around composables, with a focus on producing clean, maintainable, and testable code. Though composables may appear to be a new beast, they are fundamentally just functions. Hence, this guide grounds its recommendations in time-tested principles of good software design.
Whether you’re just stepping into Vue 3 or are an experienced developer aiming to standardize your team’s coding style, this guide serves as a comprehensive resource.
Table of Contents
Open Table of Contents
File Naming
Rule 1.1: Prefix with use and Follow PascalCase
// Good
useCounter.ts;
useApiRequest.ts;
// Bad
counter.ts;
APIrequest.ts;
Composable Naming
Rule 2.1: Use Descriptive Names
// Good
export function function useUserData(): voiduseUserData() {}
// Bad
export function function useData(): voiduseData() {}
Folder Structure
Rule 3.1: Place in composables Directory
src/
└── composables/
├── useCounter.ts
└── useUserData.ts
Argument Passing
Rule 4.1: Use Object Arguments for Four or More Parameters
// Good: For Multiple Parameters
useUserData({ id: numberid: 1, fetchOnMount: booleanfetchOnMount: true, token: stringtoken: "abc", locale: stringlocale: "en" });
// Also Good: For Fewer Parameters
useCounter(1, true, "session");
// Bad
useUserData(1, true, "abc", "en");
Error Handling
Rule 5.1: Expose Error State
// Good
const const error: anyerror = ref(null);
try {
// Do something
} catch (var err: unknownerr) {
const error: anyerror.value = var err: unknownerr;
}
return { error: anyerror };
// Bad
try {
// Do something
} catch (var err: unknownerr) {
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without calling `require('console')`.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.error(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stderr` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).
```js
const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr
```
If formatting elements (e.g. `%d`) are not found in the first string then
[`util.inspect()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilinspectobject-options) is called on each argument and the
resulting string values are concatenated. See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)
for more information.error("An error occurred:", var err: unknownerr);
}
return {};
Avoid Mixing UI and Business Logic
Rule 6.2: Decouple UI from Business Logic in Composables
Composables should focus on managing state and business logic, avoiding UI-specific behavior like toasts or alerts. Keeping UI logic separate from business logic will ensure that your composable is reusable and testable.
// Good
export function function useUserData(userId: any): {
user: any;
error: any;
fetchUser: () => Promise<void>;
} (+1 overload)
userId: anyuserId) {
const const user: anyuser = ref(null);
const const error: anyerror = ref(null);
const const fetchUser: () => Promise<void>fetchUser = async () => {
try {
const const response: anyresponse = await axios.get(`/api/users/${userId: anyuserId}`);
const user: anyuser.value = const response: anyresponse.data;
} catch (function (local var) e: unknowne) {
const error: anyerror.value = function (local var) e: unknowne;
}
};
return { user: anyuser, error: anyerror, fetchUser: () => Promise<void>fetchUser };
}
// In component
setup() {
const { const user: anyuser, const error: anyerror, const fetchUser: () => Promise<void>fetchUser } = function useUserData(userId: any): {
user: any;
error: any;
fetchUser: () => Promise<void>;
} (+1 overload)
const error: anyerror, (newValue: anynewValue) => {
if (newValue: anynewValue) {
showToast("An error occurred."); // UI logic in component
}
});
return { user: anyuser, fetchUser: () => Promise<void>fetchUser };
}
// Bad
export function function useUserData(userId: any): {
user: any;
error: any;
fetchUser: () => Promise<void>;
} (+1 overload)
userId: anyuserId) {
const const user: anyuser = ref(null);
const const fetchUser: () => Promise<void>fetchUser = async () => {
try {
const const response: anyresponse = await axios.get(`/api/users/${userId: anyuserId}`);
const user: anyuser.value = const response: anyresponse.data;
} catch (function (local var) e: unknowne) {
showToast("An error occurred."); // UI logic inside composable
}
};
return { user: anyuser, fetchUser: () => Promise<void>fetchUser };
}
Anatomy of a Composable
Rule 7.2: Structure Your Composables Well
A composable that adheres to a well-defined structure is easier to understand, use, and maintain. Ideally, it should consist of the following components:
- Primary State: The main read-only state that the composable manages.
- Supportive State: Additional read-only states that hold values like the status of API requests or errors.
- Methods: Functions responsible for updating the Primary and Supportive states. These can call APIs, manage cookies, or even call other composables.
By ensuring your composables follow this anatomical structure, you make it easier for developers to consume them, which can improve code quality across your project.
// Good Example: Anatomy of a Composable
// Well-structured according to Anatomy of a Composable
export function function useUserData(userId: any): {
user: any;
status: any;
error: any;
fetchUser: () => Promise<void>;
}
userId: anyuserId) {
// Primary State
const const user: anyuser = ref(null);
// Supportive State
const const status: anystatus = ref("idle");
const const error: anyerror = ref(null);
// Methods
const const fetchUser: () => Promise<void>fetchUser = async () => {
const status: anystatus.value = "loading";
try {
const const response: anyresponse = await axios.get(`/api/users/${userId: anyuserId}`);
const user: anyuser.value = const response: anyresponse.data;
const status: anystatus.value = "success";
} catch (function (local var) e: unknowne) {
const status: anystatus.value = "error";
const error: anyerror.value = function (local var) e: unknowne;
}
};
return { user: anyuser, status: anystatus, error: anyerror, fetchUser: () => Promise<void>fetchUser };
}
// Bad Example: Anatomy of a Composable
// Lacks well-defined structure and mixes concerns
export function function useUserDataAndMore(userId: any): {
user: any;
count: any;
message: any;
fetchUserAndIncrement: () => Promise<void>;
setMessage: (newMessage: any) => void;
}
userId: anyuserId) {
// Muddled State: Not clear what's Primary or Supportive
const const user: anyuser = ref(null);
const const count: anycount = ref(0);
const const message: anymessage = ref("Initializing...");
// Methods: Multiple responsibilities and side-effects
const const fetchUserAndIncrement: () => Promise<void>fetchUserAndIncrement = async () => {
const message: anymessage.value = "Fetching user and incrementing count...";
try {
const const response: anyresponse = await axios.get(`/api/users/${userId: anyuserId}`);
const user: anyuser.value = const response: anyresponse.data;
} catch (function (local var) e: unknowne) {
const message: anymessage.value = "Failed to fetch user.";
}
const count: anycount.value++; // Incrementing count, unrelated to user fetching
};
// More Methods: Different kind of task entirely
const const setMessage: (newMessage: any) => voidsetMessage = newMessage: anynewMessage => {
const message: anymessage.value = newMessage: anynewMessage;
};
return { user: anyuser, count: anycount, message: anymessage, fetchUserAndIncrement: () => Promise<void>fetchUserAndIncrement, setMessage: (newMessage: any) => voidsetMessage };
}
Functional Core, Imperative Shell
Rule 8.2: (optional) use functional core imperative shell pattern
Structure your composable such that the core logic is functional and devoid of side effects, while the imperative shell handles the Vue-specific or side-effecting operations. Following this principle makes your composable easier to test, debug, and maintain.
Example: Functional Core, Imperative Shell
// good
// Functional Core
const const calculate: (a: any, b: any) => anycalculate = (a: anya, b: anyb) => a: anya + b: anyb;
// Imperative Shell
export function function useCalculatorGood(): {
result: any;
add: (a: any, b: any) => void;
}
const result: anyresult = ref(0);
const const add: (a: any, b: any) => voidadd = (a: anya, b: anyb) => {
const result: anyresult.value = const calculate: (a: any, b: any) => anycalculate(a: anya, b: anyb); // Using the functional core
};
// Other side-effecting code can go here, e.g., logging, API calls
return { result: anyresult, add: (a: any, b: any) => voidadd };
}
// wrong
// Mixing core logic and side effects
export function function useCalculatorBad(): {
result: any;
add: (a: any, b: any) => void;
}
const result: anyresult = ref(0);
const const add: (a: any, b: any) => voidadd = (a: anya, b: anyb) => {
// Side-effect within core logic
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without calling `require('console')`.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).
```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```
See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.log("Adding:", a: anya, b: anyb);
const result: anyresult.value = a: anya + b: anyb;
};
return { result: anyresult, add: (a: any, b: any) => voidadd };
}
Single Responsibility Principle
Rule 9.1: Use SRP for composables
A composable should adhere to the Single Responsibility Principle, meaning it should have only one reason to change. In other words, a composable should have only one job or responsibility. A violation of this principle can result in composables that are difficult to understand, maintain, and test.
// Good
export function function useCounter(): {
count: any;
increment: () => void;
decrement: () => void;
}
const count: anycount = ref(0);
const const increment: () => voidincrement = () => {
const count: anycount.value++;
};
const const decrement: () => voiddecrement = () => {
const count: anycount.value--;
};
return { count: anycount, increment: () => voidincrement, decrement: () => voiddecrement };
}
// Bad
export function function useUserAndCounter(userId: any): {
user: any;
fetchUser: () => Promise<void>;
count: any;
increment: () => void;
decrement: () => void;
}
userId: anyuserId) {
const const user: anyuser = ref(null);
const const count: anycount = ref(0);
const const fetchUser: () => Promise<void>fetchUser = async () => {
try {
const const response: anyresponse = await axios.get(`/api/users/${userId: anyuserId}`);
const user: anyuser.value = const response: anyresponse.data;
} catch (function (local var) error: unknownerror) {
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without calling `require('console')`.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.error(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stderr` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).
```js
const code = 5;
console.error('error #%d', code);
// Prints: error #5, to stderr
console.error('error', code);
// Prints: error 5, to stderr
```
If formatting elements (e.g. `%d`) are not found in the first string then
[`util.inspect()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilinspectobject-options) is called on each argument and the
resulting string values are concatenated. See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)
for more information.error("An error occurred while fetching user data:", function (local var) error: unknownerror);
}
};
const const increment: () => voidincrement = () => {
const count: anycount.value++;
};
const const decrement: () => voiddecrement = () => {
const count: anycount.value--;
};
return { user: anyuser, fetchUser: () => Promise<void>fetchUser, count: anycount, increment: () => voidincrement, decrement: () => voiddecrement };
}
File Structure of a Composable
Rule 10.1: Rule: Consistent Ordering of Composition API Features
While the precise order can be adapted to meet the needs of your project or team, it is crucial that the chosen order is maintained consistently throughout your codebase.
Here’s a suggestion for a file structure:
- Initializing: Code for setting up initialization logic.
- Refs: Code for reactive references.
- Computed: Code for computed properties.
- Methods: Functions and methods that will be used.
- Lifecycle Hooks: Lifecycle hooks like onMounted, onUnmounted, etc.
- Watch
this is just one example of a possible order, its just important that you have an order and ideally in your project the order is always the same
// Example in useCounter.ts
import { function ref<T>(value: T): [T] extends [Ref] ? IfAny<T, Ref<T>, T> : Ref<UnwrapRef<T>, UnwrapRef<T> | T> (+1 overload)Takes an inner value and returns a reactive and mutable ref object, which
has a single property `.value` that points to the inner value.ref, const computed: {
<T>(getter: ComputedGetter<T>, debugOptions?: DebuggerOptions): ComputedRef<T>;
<T, S = T>(options: WritableComputedOptions<T, S>, debugOptions?: DebuggerOptions): WritableComputedRef<T, S>;
}
const onMounted: CreateHook<any>onMounted } from "vue";
export default function function useCounter(): {
count: Ref<number, number>;
isEven: ComputedRef<boolean>;
increment: () => void;
decrement: () => void;
}
const count: Ref<number, number>count = ref<number>(value: number): Ref<number, number> (+1 overload)Takes an inner value and returns a reactive and mutable ref object, which
has a single property `.value` that points to the inner value.ref(0);
// Computed
const const isEven: ComputedRef<boolean>isEven = computed<boolean>(getter: ComputedGetter<boolean>, debugOptions?: DebuggerOptions): ComputedRef<boolean> (+1 overload)Takes a getter function and returns a readonly reactive ref object for the
returned value from the getter. It can also take an object with get and set
functions to create a writable ref object.computed(() => const count: Ref<number, number>count.Ref<number, number>.value: numbervalue % 2 === 0);
// Methods
const const increment: () => voidincrement = () => {
const count: Ref<number, number>count.Ref<number, number>.value: numbervalue++;
};
const const decrement: () => voiddecrement = () => {
const count: Ref<number, number>count.Ref<number, number>.value: numbervalue--;
};
// Lifecycle
function onMounted(hook: any, target?: ComponentInternalInstance | null): voidonMounted(() => {
var console: ConsoleThe `console` module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
* A `Console` class with methods such as `console.log()`, `console.error()` and `console.warn()` that can be used to write to any Node.js stream.
* A global `console` instance configured to write to [`process.stdout`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstdout) and
[`process.stderr`](https://nodejs.org/docs/latest-v22.x/api/process.html#processstderr). The global `console` can be used without calling `require('console')`.
_**Warning**_: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the [`note on process I/O`](https://nodejs.org/docs/latest-v22.x/api/process.html#a-note-on-process-io) for
more information.
Example using the global `console`:
```js
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
```
Example using the `Console` class:
```js
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
```console.Console.log(message?: any, ...optionalParams: any[]): void (+1 overload)Prints to `stdout` with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to [`printf(3)`](http://man7.org/linux/man-pages/man3/printf.3.html)
(the arguments are all passed to [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args)).
```js
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
```
See [`util.format()`](https://nodejs.org/docs/latest-v22.x/api/util.html#utilformatformat-args) for more information.log("Counter is mounted");
});
return {
count: Ref<number, number>count,
isEven: ComputedRef<boolean>isEven,
increment: () => voidincrement,
decrement: () => voiddecrement,
};
}
Conclusion
The guidelines presented in this article aim to offer best practices for writing clean, testable, and efficient Vue 3 composables. While these recommendations stem from a mix of established software design principles and practical experience, they are by no means exhaustive or universally applicable.
Programming is often more of an art than a science. As you grow in your Vue journey, you may find different strategies and patterns that work better for your specific use-cases. The key is to maintain a consistent, scalable, and maintainable codebase. Therefore, feel free to adapt these guidelines according to the needs of your project.
I’m open to further ideas, improvements, and real-world examples. If you have any suggestions or different approaches that work well for you, please don’t hesitate to share in the comments below. Together, we can evolve these guidelines to be an even more useful resource for the Vue community.