Composable definition in vue file. Is it wrong?

[DouglasCalora]

I have a pattern I follow: every time I create a composable to be reused, I create a ".js" file. However, when I create a composable just to separate code/context that won't be shared, I create the definition within the .vue file itself.

Is this considered bad practice? The documentation doesn't make this clear.

Let’s say I have a component AppDisplayValue that receives two props: type and value.

If the type is x, the component performs an internal normalization process using multiple layers of logic, such as computed properties, watchers, and other internal transformations.

If the type is y, it follows a completely different flow, where it retrieves a normalized value from the server, something similar to handling relationships.

In this scenario, it is still the same component, but with distinct internal behaviors depending on the type used to render the UI.

To improve separation of concerns and make the context clearer

function useInternalValue () { ... }
function useRemoteValue () { ... }

Exemple of functions...

function useRemoteValue () {
  const remoteValue = ref(...)
  const isLoading = ref(false)
  const error = ref(null)

  watch(() => props.type, fetchRemoteValue)

  onMounted(fetchRemoteValue)

  const myComputedXPTO = computed(() => {
    // ...
  })

  function fetchRemoteValue() { ... }

  function additionalLogicXPTO () { ... }

  return {
    remoteValue,
    isLoading,
    error
  }
}

function useInternalValue () {
  const internalValue = ref(...)

  watch(() => props.type, parseValue)
  watch(() => props.status, additionalLogicInternalXPTO)

  onMounted(parseValue)

  const myComputedInternalXPTO = computed(() => {
    // ...
  })

  function parseValue() { ... }

  function additionalLogicInternalXPTO () { ... }

  return {
    internalValue,
    myComputedInternalXPTO,
    additionalLogicXPTO
  }
}

The key point is that these composables are not intended to be reused anywhere else in the application. Because of that, I define them directly inside the same .vue component where they are used (AppDisplayValue).

[ELHart05]

Inline Composables Inside .vue Files "Not a Bad Practice"

Short answer: no, it's not bad practice. The Vue documentation promotes the composable pattern "reactive logic wrapped in a function using the Composition API" but it doesn't say every composable has to live in its own file. What matters is the shape of the code, not where it physically sits.

What the Docs Actually Say

The Vue docs define a composable as a function that "leverages Vue's Composition API to encapsulate and reuse stateful logic." The key word there is encapsulation, not reuse. File location is a convention that emerges from reuse requirements, it's not a hard rule. Defining useRemoteValue() or useInternalValue() inside AppDisplayValue.vue is perfectly idiomatic when those functions are local concerns that don't need to travel anywhere else.

Why This Pattern Is Sound

Think of it like class methods in OOP. Not every helper method becomes a standalone utility just because it theoretically could. The same logic applies here:

• Logic reused across multiple components → separate .js / .ts file, so it's importable and testable in isolation
• Logic that separates concerns within one component => inline in the .vue file, encapsulated, no cross-component contract needed

This distinction is principled and well-aligned with how good software is actually organized.

What Your Code Does Well

Both useRemoteValue and useInternalValue follow the composable contract correctly. They close over reactive dependencies like props.type rather than raw values, which keeps them reactive. They register lifecycle hooks (onMounted, watch) internally, that's the thing that actually separates a composable from a plain utility function. And they return only what the template or setup() needs, with no internal state leaking out.

That's clean Composition API design, full stop, regardless of which file it lives in.

One Thing Worth Noting: Props via Closure

Because these composables are defined inside <script setup>, they close over props directly. This works great for inline use. If you ever decide to extract one to a separate file, you'll need to pass the relevant reactive values as arguments:

//an example where props passed explicitly :)
function useRemoteValue(props) {
  watch(() => props.type, fetchRemoteValue)
  // ...
}

It's a small refactor, not a structural problem. And honestly, the fact that the inline version makes the dependency obvious from the start is a point in its favor.

When to Actually Extract

There are a few natural signals that tell you it's time to pull a composable into its own file:

• Another component needs the same logic, this is the original reason extraction exists
• The composable grows large enough that the .vue file becomes hard to navigate (somewhere around 50+ lines of composable logic is a reasonable gut check)
• You want to unit test it in isolation with Vitest or Jest without mounting a full component
• It could be useful in other projects and is worth documenting as a standalone piece

Outside of those cases, keeping it inline is not just acceptable, it's arguably the better choice. It keeps related logic co-located and avoids the kind of premature abstraction that makes codebases harder to follow, not easier.

The Bigger Picture

This pattern shows up in production codebases and is consistent with how the Vue core team talks about the Composition API. The <script setup> RFC explicitly allows for local composables, functions defined in the same file that use watch, computed, onMounted, and so on.

The goal of composables has always been better organization. More files is just one way to get there, not the destination itself.

I hope it helped!

[chrisjcthomas]

Defining composables inside a .vue Single File Component (SFC) is not bad practice at all. In fact, it is an excellent pattern for keeping logic organized and localized when a composable is highly specific to a single component and has no reuse value elsewhere.

Benefits of Inline Composables:

1. Locality of Behavior: The business logic remains close to the template that consumes it, making the file easier to read and maintain.
2. Refactoring Path: If you later need to reuse useRemoteValue or useInternalValue in another component, it is trivial to cut and paste them into a separate .ts or .js file.
3. Encapsulation: It keeps the global project structure clean by avoiding file pollution with single-use utility files.

Guidelines for Defining Inline Composables:

• Define Outside the Component Export: Always define your composable functions outside the defineComponent or setup scope (typically at the bottom of your <script> block). This avoids recreating the functions on every render or state change.
• Handling Component Props Reactively: When defining the composables outside the setup function, they cannot read component props directly. You must pass props down as reactive references or getter functions:

<script setup>
import { ref, computed, onMounted, watch } from 'vue';

const props = defineProps({
  type: String,
  status: String
});

// Pass props reactively as getters
const { remoteValue, isLoading } = useRemoteValue(() => props.type);
</script>

<script>
// Define the composable outside the setup scope
function useRemoteValue(getType) {
  const remoteValue = ref(null);
  const isLoading = ref(false);

  // Watch the getter function for reactivity
  watch(getType, (newType) => {
    fetchRemoteValue(newType);
  });

  onMounted(() => fetchRemoteValue(getType()));

  function fetchRemoteValue(type) {
    // ...
  }

  return { remoteValue, isLoading };
}
</script>