Vue의 ref, shallowRef, reactive, shallowReactive 차이

들어가며

Vue 3의 Composition API를 사용하다 보면 반응형 데이터를 만드는 방법이 여러 가지라 헷갈릴 때가 있습니다. ref, shallowRef, reactive, shallowReactive… 이름은 비슷한데 동작은 미묘하게 다릅니다.

이 글에서는 네 가지 API의 차이를 코드와 함께 정리해보겠습니다.

ref vs reactive

가장 기본적인 두 가지부터 비교해봅시다.

ref

ref는 어떤 타입의 값이든 반응형으로 만들 수 있습니다. 원시값(string, number, boolean)은 물론 객체도 가능합니다.

<script setup>
import { ref } from "vue";

const count = ref(0);
const user = ref({ name: "Kwan", age: 30 });

// .value로 접근
count.value++;
user.value.name = "Lee"; // 깊은 속성 변경도 반응형으로 감지
</script>

ref는 .value로 감싸진 객체를 반환합니다. 값에 접근하거나 변경할 때 항상 .value를 거쳐야 합니다. 단, 템플릿에서는 자동으로 언래핑되어 .value 없이 사용할 수 있습니다.

객체를 ref에 넣으면 내부적으로 reactive를 사용하여 깊은(deep) 반응형이 적용됩니다. 중첩된 속성을 변경해도 감지됩니다.

reactive

reactive는 객체 타입(Object, Array, Map, Set 등) 만 반응형으로 만들 수 있습니다. 원시값은 사용할 수 없습니다.

<script setup>
import { reactive } from "vue";

const user = reactive({ name: "Kwan", age: 30 });

// .value 없이 직접 접근
user.name = "Lee"; // 반응형으로 감지
</script>

.value 없이 직접 속성에 접근할 수 있다는 점이 편리하지만, 몇 가지 제약이 있습니다.

// 1. 원시값 사용 불가
const count = reactive(0); // 동작하지 않음

// 2. 구조분해하면 반응성을 잃음
const { name, age } = reactive({ name: "Kwan", age: 30 });
// name, age는 더 이상 반응형이 아님

// 3. 재할당하면 반응성을 잃음
let user = reactive({ name: "Kwan" });
user = reactive({ name: "Lee" }); // 기존 참조와 연결 끊김

정리

Vue 공식 문서에서도 ref를 기본으로 사용하는 것을 권장합니다. reactive의 제약 사항들 때문에 예상치 못한 버그를 만들기 쉽기 때문입니다.

shallowRef vs shallowReactive

ref와 reactive는 모두 깊은(deep) 반응형입니다. 중첩된 객체의 어떤 속성을 바꿔도 감지합니다. 하지만 큰 객체에서 깊은 반응형이 불필요하다면 성능상 부담이 될 수 있습니다.

이때 사용하는 것이 shallowRef와 shallowReactive입니다. 얕은(shallow) 반응형으로, 최상위 레벨만 감지합니다.

shallowRef

<script setup>
import { shallowRef } from "vue";

const user = shallowRef({ name: "Kwan", age: 30 });

// .value 자체를 교체하면 반응형으로 감지
user.value = { name: "Lee", age: 25 }; // 감지됨

// 깊은 속성 변경은 감지되지 않음
user.value.name = "Park"; // 감지 안 됨 (UI 업데이트 없음)
</script>

shallowRef는 .value의 교체만 추적합니다. 내부 속성을 직접 바꾸면 Vue가 알아채지 못합니다.

그런데 원시값(number, string 등)을 shallowRef에 넣으면 어떨까요? 원시값은 애초에 중첩 속성이 없기 때문에 .value 교체가 곧 값 변경입니다. 즉, 깊은 반응형 변환이 발생할 여지가 없어 ref보다 불필요한 오버헤드 없이 동작합니다.

import { shallowRef } from 'vue'

const count = shallowRef(0)

count.value = 10 // 감지됨 (원시값은 항상 .value 교체이므로 자연스럽게 동작)

단순한 원시값 상태를 다룰 때 shallowRef를 사용하면, 값이 객체로 확장되더라도 의도치 않은 깊은 반응형 변환을 방지할 수 있어 성능 면에서 유리합니다.

깊은 속성을 변경한 뒤 강제로 반응시키고 싶다면 triggerRef()를 사용할 수 있습니다.

import { shallowRef, triggerRef } from "vue";

const user = shallowRef({ name: "Kwan" });

user.value.name = "Lee"; // 이것만으로는 UI 업데이트 안 됨
triggerRef(user); // 수동으로 트리거하면 UI 업데이트

shallowReactive

<script setup>
import { shallowReactive } from "vue";

const state = shallowReactive({
  name: "Kwan",
  nested: { count: 0 },
});

// 최상위 속성 변경은 감지
state.name = "Lee"; // 감지됨

// 중첩 속성 변경은 감지 안 됨
state.nested.count++; // 감지 안 됨 (UI 업데이트 없음)
</script>

shallowReactive는 객체의 1depth 속성만 반응형으로 추적합니다. 중첩된 객체의 변경은 감지하지 않습니다.

언제 shallow를 쓸까?

대부분의 경우에는 ref와 reactive로 충분합니다. shallow 버전은 다음과 같은 상황에서 고려하면 좋습니다.

• 큰 리스트나 복잡한 객체를 다루는데, 내부 속성의 변경을 일일이 추적할 필요가 없을 때
• 외부 라이브러리의 객체를 반응형으로 감싸야 하지만, 내부 구조까지 프록시로 만들고 싶지 않을 때
• 성능 최적화가 필요한 경우 (깊은 반응형은 중첩된 모든 속성에 프록시를 생성)

실제로 Vue의 내부 코드에서도 컴포넌트 인스턴스를 shallowReactive로 관리합니다. 모든 내부 속성까지 깊게 추적할 필요가 없기 때문이죠.

마치며

네 가지 API를 한 줄로 정리하면 이렇습니다.

기본적으로는 ref를 사용하고, 성능 최적화가 필요한 특수한 경우에만 shallow 버전을 고려하는 것이 좋겠습니다. reactive는 .value 없이 사용할 수 있어 편리하지만 구조분해나 재할당 시 반응성을 잃는 제약이 있으니 주의해서 사용합시다.

참고 자료

• Vue 공식 문서 - Reactivity API: Core
• Vue 공식 문서 - Reactivity API: Advanced
• Vue 공식 문서 - Reactivity in Depth