React Native 내비게이션 오류 해결 방법: 'Screen' 컴포넌트 직접 자식 문제

문제 상황

React Native에서 내비게이션(Navigation)을 구현하다 보면 다음과 같은 오류 메시지를 만나게 될 수 있습니다.

A navigator can only contain 'Screen' components as its direct children
— 내비게이터의 직접적인 자식 요소로는 'Screen' 컴포넌트만 포함할 수 있다는 의미입니다.

앱 개발 과정에서 누구나 한 번쯤 겪을 수 있는 이 오류는 대부분 사소한 코드 작성 습관에서 비롯됩니다. 이번 글에서는 오류가 발생하는 원인과 해결 방법을 실제 코드 예시와 함께 자세히 알아보겠습니다.

오류가 발생하는 코드 예시

먼저 해당 오류를 유발하는 코드부터 확인해 보겠습니다.

App.js

import * as React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import { Button, View, Alert, Text } from 'react-native';
const Stack = createStackNavigator();
const HomePage = ({ navigation }) => {
    return (
        <Button title="Click Here" onPress={() => navigation.navigate('About', { name: 'About Page' })} />
    );
};
const AboutPage = () => {
    return <Text>You have reached inside About Page!</Text>;
};
const MyStack = () => {
    return (
        <NavigationContainer>
            <Stack.Navigator>
                <Stack.Screen name="Home" component={HomePage} options={{ title: 'From home page : Navigation' }} />
                <Stack.Screen name="About" component={AboutPage} />
            </Stack.Navigator>
        </NavigationContainer>
    );
};
export default MyStack;

이 코드를 컴파일하면 명령 프롬프트에 다음과 같은 오류가 출력됩니다.

실제 기기 화면에 표시되는 오류 모습은 다음과 같습니다.

오류의 주요 원인

1. 잘못된 들여쓰기(Indentation)

첫 번째 원인은 들여쓰기가 제대로 지켜지지 않은 경우입니다. 각 컴포넌트는 반드시 올바르게 들여쓰기해야 하며, 자식 요소들은 부모 컴포넌트 내부에서 일정한 깊이로 정렬되어야 합니다. 특히 속성을 여러 줄에 걸쳐 작성할 때 들여쓰기가 어긋나면 코드 구조가 불안정해져 오류가 발생하기 쉽습니다.

2. 컴포넌트 끝에 남은 공백과 숨은 문자

두 번째 원인은 각 컴포넌트(특히 Screen 태그) 끝에 남아 있는 불필요한 공백입니다. 태그 끝의 공백을 제거한 뒤 다시 컴파일하면 정상적으로 동작하는 경우가 많습니다. 블로그나 다른 프로젝트에서 코드를 복사해 붙여넣을 때 보이지 않는 공백 문자나 특수 문자가 함께 들어오면서 이런 오류가 자주 발생하므로, 복사-붙여넣기 후에는 반드시 코드를 한 번 점검하는 습관을 들이는 것이 좋습니다.

3. Navigator 바로 아래에 Screen 외 요소 배치

참고로 이 오류의 가장 일반적인 원인은 Stack.Navigator의 직접 자식 위치에 Screen이 아닌 다른 컴포넌트(View, Text 등)나 조건부 렌더링 결과물을 넣는 것입니다. Navigator 내부에는 반드시 Stack.Screen 컴포넌트만 배치해야 하며, 실제 화면 UI는 각 Screen의 component prop으로 전달되는 컴포넌트 안에 작성해야 합니다.

수정된 최종 코드

이제 위 코드의 들여쓰기를 정리하고 불필요한 공백을 제거해 보겠습니다. 아래는 수정 후 정상적으로 동작하는 최종 코드입니다.

import * as React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { createStackNavigator } from '@react-navigation/stack';
import { Button, View, Alert, Text } from 'react-native';
const Stack = createStackNavigator();
const HomePage = ({ navigation }) => {
    return (
        <Button title="Click Here" onPress={() => navigation.navigate('About', { name: 'About Page' })} />
    );
};
const AboutPage = () => {
    return <Text>You have reached inside About Page!</Text>;
};
const MyStack = () => {
    return (
        <NavigationContainer>
            <Stack.Navigator>
                <Stack.Screen name="Home" component={HomePage} options={{ title: 'From home page : Navigation' }} />
                <Stack.Screen name="About" component={AboutPage} />
            </Stack.Navigator>
        </NavigationContainer>
    );
};
export default MyStack;

정리

React Native 내비게이션 관련 오류는 대부분 코드 구조와 포맷팅 문제에서 비롯됩니다. Navigator의 직접 자식으로는 Screen 컴포넌트만 두고, 들여쓰기와 공백을 꼼꼼히 점검하면 이런 오류를 충분히 예방할 수 있습니다. 외부 코드를 가져올 때는 항상 전체 구조를 확인하는 습관을 기르는 것이 좋습니다.