[RN] 🛖 React Native with Expo (SDK 54) 사용법 — Router, Modal, API Routes, NativeWind v5 설정

▷ Expo 사용법 (sdk 54)


# 설치
npx create-expo-app@latest

# 실행
pnpm start
# 캐시 리셋
# npx expo start -c

# android 실행
a
# ios 실행
i

🛖 Routing

File-based routing core-concepts

Expo는 Next.js처럼 app/ 폴더 기반의 파일 라우팅을 쓴다. 여기에 API Routes(서버 코드) 까지 app/ 안에서 함께 다룰 수 있다. (Web 전용)

파일 위치	실제 경로	설명
`app/(auth)/login.tsx`	`/login`	`(auth)` 폴더 이름은 URL에 포함되지 않음
`app/(tabs)/profile.tsx`	`/profile`	그룹 이름은 단지 라우트 구조 정리용
`app/(tabs)/_layout.tsx`	`/` 기준에서 탭 네비게이션을 구성
`app/_layout.tsx`	앱 전체 루트 네비게이션


my-app/
├─ app/
│  ├─ _layout.tsx            # 중첩 네비게이션(Stack/Tabs 등) 레이아웃
│  ├─ index.tsx              # "/" 루트 화면
│  ├─ (marketing)/           # 라우트 그룹(경로에 표시 안 됨)
│  │   └─ landing.tsx        # "/landing"
│  ├─ users/
│  │   ├─ [id].tsx           # 동적 세그먼트 => "/users/42"
│  │   └─ [id]/settings.tsx  # 중첩 동적 경로
│  ├─ +not-found.tsx         # 404 처리
│  ├─ hello+api.ts           # "/hello" API 라우트 (GET/POST 등)
│  └─ auth/
│      └─ login+api.ts       # "/auth/login" API 라우트
├─ app.json                  # web.output=server 설정(서버 번들)
├─ package.json
└─ ...

🛖 Route Group

괄호 폴더: 구조만, 경로엔 안 들어감

파일 위치	실제 경로	설명
`app/(auth)/login.tsx`	`/login`	`(auth)` 폴더 이름은 URL에 포함되지 않음
`app/(tabs)/profile.tsx`	`/profile`	그룹 이름은 단지 라우트 구조 정리용
`app/(tabs)/_layout.tsx`	`/` 기준에서 탭 네비게이션을 구성
`app/_layout.tsx`	앱 전체 루트 네비게이션


app/
├─ (auth)/
│   ├─ login.tsx
│   ├─ register.tsx
│   └─ _layout.tsx
├─ (tabs)/
│   ├─ home.tsx
│   ├─ profile.tsx
│   └─ _layout.tsx
├─ index.tsx
└─ _layout.tsx

🛖 Screen Routing (ft. useLocalSearchParams)

화면 라우팅


// app/_layout.tsx
import { Stack } from 'expo-router';

export default function RootLayout() {
  return <Stack screenOptions={{ headerShown: false }} />;
}

// app/index.tsx
import { Link } from 'expo-router';
import { View, Text } from 'react-native';

export default function Home() {
  return (
    <View>
      <Text>Home</Text>
      <Link href="/users/42">Go user 42</Link>
    </View>
  );
}

// app/users/[id].tsx
import { useLocalSearchParams } from 'expo-router';
export default function User() {
  const { id } = useLocalSearchParams();
  return null;
}

🛖 modal

modal


app/
├─ _layout.tsx
├─ index.tsx
└─ modal.tsx

모달 화면을 구성


/* app/_layout.tsx */
import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native';
import { Stack } from 'expo-router';
import { StatusBar } from 'expo-status-bar';
import 'react-native-reanimated';
import './global.css';

import { useColorScheme } from '@/hooks/use-color-scheme';

/* anchor는 딥링크나 모달 dismiss 시, 앱이 돌아갈 기준 루트를 지정하는 옵션이다. */
export const unstable_settings = {
  anchor: '(tabs)',
};

export default function RootLayout() {
  const colorScheme = useColorScheme();

  return (
    <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen name="modal" options={{ presentation: 'modal', title: 'Modal' }} />
      </Stack>
      <StatusBar style="auto" />
    </ThemeProvider>
  );
}

모달 화면으로 이동


/* app/index.tsx */
import { Link } from 'expo-router';
import { Text, View } from 'react-native';

export default function Home() {
  return (
    <View>
      <Text>Home screen</Text>
      <Link href="/modal">
        Open modal
      </Link>
    </View>
  );
}

모달 전용 화면


/* app/modal.tsx */
import { Link } from 'expo-router';
import { StyleSheet } from 'react-native';

import { ThemedText } from '@/components/themed-text';
import { ThemedView } from '@/components/themed-view';

export default function ModalScreen() {
  return (
    <ThemedView style={styles.container}>
      <ThemedText type="title">This is a modal</ThemedText>
      <Link href="/" dismissTo style={styles.link}>
        <ThemedText type="link">Go to home screen</ThemedText>
      </Link>
    </ThemedView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 20,
  },
  link: {
    marginTop: 15,
    paddingVertical: 15,
  },
});

(modal) 폴더로 묶어서 쓰는 패턴도 자주 사용함


app/
  _layout.tsx
  (tabs)/
    _layout.tsx
    index.tsx
  (modal)/
    _layout.tsx   // 여기서 presentation: "modal" 그룹 처리
    settings.tsx

FormSheet 모달 옵션 설정


import { Stack } from 'expo-router';
import { View, Button } from 'react-native';

function Layout() {
  return (
    <Stack>
      {/* 기본 메인 화면(index.tsx) 라우트 */}
      <Stack.Screen name="index" />

      <Stack.Screen
        name="modal"
        options={{
          /* 모달을 어떤 스타일로 띄울지 결정 (iOS에서 formSheet 형태로 표시됨) */
          presentation: 'formSheet',

          /* sheet(바텀시트)가 가질 수 있는 높이 단계(detent) 목록 (0~1 비율) */
          sheetAllowedDetents: [0.25, 0.5, 1],

          /* 처음 모달이 열릴 때 시작할 detent 단계 인덱스 (0이면 0.25부터 시작) */
          sheetInitialDetentIndex: 0,

          /* 상단에 드래그 가능한 grabber(손잡이)를 표시할지 여부 */
          sheetGrabberVisible: true,

          /* sheet 모서리 둥글기 값 (px 단위) */
          sheetCornerRadius: 24,

          /* sheet가 확장될 때 dim(배경 어두워짐)이 적용되지 않는 최대 detent 인덱스 */
          /* 예: 1이면 0.5 단계까지는 배경이 안 어두워지고, 그 이상부터 dim 적용 */
          sheetLargestUndimmedDetentIndex: 1,

          /* 푸터 추가 (sheet 하단에 고정되는 footer UI 영역) */
          unstable_sheetFooter: () => (
            <View style={{ padding: 16, backgroundColor: 'white' }}>
              <Button title="Confirm" onPress={() => {}} />
            </View>
          ),
        }}
      />
    </Stack>
  );
}

export default Layout;

🛖 API Routes (Web 전용)

API Routes

Web(Server output)에서만 동작하는 서버 엔드포인트이다.

API Routes(서버 엔드포인트): app폴더 안에서 서버 코드

app/ 폴더 안에서 +api.ts 확장자 파일을 만들면 그 경로가 서버 엔드포인트가 된다. (Next.js app/**/route.ts와 비슷한 개념)


// app/hello+api.ts  -> GET /hello
export async function GET(request: Request) {
  return Response.json({ hello: 'world' });
}

// 동적·중첩도 동일 규칙
// app/users/[id]/profile+api.ts -> /users/:id/profile
export async function POST(request: Request) {
  const body = await request.json();
  return Response.json({ ok: true, body });
}

API Routes를 위한 서버 번들기


/* app.json */
{
  "expo": {
    "web": {
      "output": "server"
    }
  }
}

🛖 nativewind v5

nativewind installation

Working package.json Dependencies


{
  "main": "expo-router/entry",
  "dependencies": {
    "expo": "~54.0.33",
    "nativewind": "^5.0.0",
    "react-native-css": "latest",
    "react-native-reanimated": "~4.1.1",
    "react-native-safe-area-context": "~5.6.0",
    "react-native-worklets": "0.5.1"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4.1.18",
    "postcss": "^8.5.6",
    "tailwindcss": "^4.1.18",
  },
  "pnpm": {
    "overrides": {
      "lightningcss": "1.30.1"
    }
  },
  "private": true
}

babel.config.js


module.exports = function (api) {
  api.cache(true);

  return {
    presets: ['babel-preset-expo'],
    plugins: [
      'react-native-reanimated/plugin',
    ],
  };
};

metro.config.ts


// Learn more <https://docs.expo.io/guides/customizing-metro>
const { getDefaultConfig } = require('expo/metro-config');
const { withNativewind } = require('nativewind/metro');

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config);

postcss.config.mjs


export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

nativewind-env.d.ts


// @ts-ignore
/// <reference types="react-native-css/types" />

global.css


@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import 'tailwindcss/utilities.css';

@import 'nativewind/theme';

app/_layout.tsx


import '../global.css';

uniwind라는 것도 있음

🛖 svg를 컴포넌트로 사용하기

expo svg

svg 파일을 React 컴포넌트처럼 import하여 사용할 수 있도록 설정


# 설치
pnpm add react-native-svg
pnpm add -D react-native-svg-transformer

# nativewind 최신 버전과 충돌 → 5.0.0-preview.2로 고정
# pnpm i nativewind@5.0.0-preview.2

metro.config.js


// Learn more <https://docs.expo.io/guides/customizing-metro>
const { getDefaultConfig } = require('expo/metro-config');
const { withNativewind } = require('nativewind/metro');

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);

config.transformer.babelTransformerPath = require.resolve(
  "react-native-svg-transformer"
);
config.resolver.assetExts = config.resolver.assetExts.filter(
  (ext) => ext !== "svg"
);
config.resolver.sourceExts.push("svg");

module.exports = withNativewind(config);

global.d.ts


declare module "*.svg" {
  import * as React from "react";
  import { SvgProps } from "react-native-svg";
  const content: React.FC<SvgProps>;
  export default content;
}

🛖 font

expo-font

app.json


"plugins": [
  "expo-router",
    ...
  [
    "expo-font",
    {
      "fonts": [
        "./assets/fonts/PretendardVariable.ttf"
      ]
    }
  ]
],

사용하는 곳


/* components/ui/text.tsx */
import { Text as RNText, TextProps } from "react-native";

export function Text({ style, ...props }: TextProps) {
  return (
    <RNText
      {...props}
      style={[{ fontFamily: "PretendardVariable" }, style]}
    />
  );
}

useFonts 훅으로 로드가 되었는지 확인도 가능하다.


const [loaded, error] = useFonts({
  'Inter-Black': require('./assets/fonts/Inter-Black.otf'),
});

[RN] 🛖 React Native with Expo (SDK 54) 사용법 — Router, Modal, API Routes, NativeWind v5 설정

▷ Expo 사용법 (sdk 54)


# 설치
npx create-expo-app@latest

# 실행
pnpm start
# 캐시 리셋
# npx expo start -c

# android 실행
a
# ios 실행
i

🛖 Routing

File-based routing core-concepts

Expo는 Next.js처럼 app/ 폴더 기반의 파일 라우팅을 쓴다. 여기에 API Routes(서버 코드) 까지 app/ 안에서 함께 다룰 수 있다. (Web 전용)

파일 위치	실제 경로	설명
`app/(auth)/login.tsx`	`/login`	`(auth)` 폴더 이름은 URL에 포함되지 않음
`app/(tabs)/profile.tsx`	`/profile`	그룹 이름은 단지 라우트 구조 정리용
`app/(tabs)/_layout.tsx`	`/` 기준에서 탭 네비게이션을 구성
`app/_layout.tsx`	앱 전체 루트 네비게이션


my-app/
├─ app/
│  ├─ _layout.tsx            # 중첩 네비게이션(Stack/Tabs 등) 레이아웃
│  ├─ index.tsx              # "/" 루트 화면
│  ├─ (marketing)/           # 라우트 그룹(경로에 표시 안 됨)
│  │   └─ landing.tsx        # "/landing"
│  ├─ users/
│  │   ├─ [id].tsx           # 동적 세그먼트 => "/users/42"
│  │   └─ [id]/settings.tsx  # 중첩 동적 경로
│  ├─ +not-found.tsx         # 404 처리
│  ├─ hello+api.ts           # "/hello" API 라우트 (GET/POST 등)
│  └─ auth/
│      └─ login+api.ts       # "/auth/login" API 라우트
├─ app.json                  # web.output=server 설정(서버 번들)
├─ package.json
└─ ...

🛖 Route Group

괄호 폴더: 구조만, 경로엔 안 들어감

파일 위치	실제 경로	설명
`app/(auth)/login.tsx`	`/login`	`(auth)` 폴더 이름은 URL에 포함되지 않음
`app/(tabs)/profile.tsx`	`/profile`	그룹 이름은 단지 라우트 구조 정리용
`app/(tabs)/_layout.tsx`	`/` 기준에서 탭 네비게이션을 구성
`app/_layout.tsx`	앱 전체 루트 네비게이션


app/
├─ (auth)/
│   ├─ login.tsx
│   ├─ register.tsx
│   └─ _layout.tsx
├─ (tabs)/
│   ├─ home.tsx
│   ├─ profile.tsx
│   └─ _layout.tsx
├─ index.tsx
└─ _layout.tsx

🛖 Screen Routing (ft. useLocalSearchParams)

화면 라우팅


// app/_layout.tsx
import { Stack } from 'expo-router';

export default function RootLayout() {
  return <Stack screenOptions={{ headerShown: false }} />;
}

// app/index.tsx
import { Link } from 'expo-router';
import { View, Text } from 'react-native';

export default function Home() {
  return (
    <View>
      <Text>Home</Text>
      <Link href="/users/42">Go user 42</Link>
    </View>
  );
}

// app/users/[id].tsx
import { useLocalSearchParams } from 'expo-router';
export default function User() {
  const { id } = useLocalSearchParams();
  return null;
}

🛖 modal

modal


app/
├─ _layout.tsx
├─ index.tsx
└─ modal.tsx

모달 화면을 구성


/* app/_layout.tsx */
import { DarkTheme, DefaultTheme, ThemeProvider } from '@react-navigation/native';
import { Stack } from 'expo-router';
import { StatusBar } from 'expo-status-bar';
import 'react-native-reanimated';
import './global.css';

import { useColorScheme } from '@/hooks/use-color-scheme';

/* anchor는 딥링크나 모달 dismiss 시, 앱이 돌아갈 기준 루트를 지정하는 옵션이다. */
export const unstable_settings = {
  anchor: '(tabs)',
};

export default function RootLayout() {
  const colorScheme = useColorScheme();

  return (
    <ThemeProvider value={colorScheme === 'dark' ? DarkTheme : DefaultTheme}>
      <Stack>
        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />
        <Stack.Screen name="modal" options={{ presentation: 'modal', title: 'Modal' }} />
      </Stack>
      <StatusBar style="auto" />
    </ThemeProvider>
  );
}

모달 화면으로 이동


/* app/index.tsx */
import { Link } from 'expo-router';
import { Text, View } from 'react-native';

export default function Home() {
  return (
    <View>
      <Text>Home screen</Text>
      <Link href="/modal">
        Open modal
      </Link>
    </View>
  );
}

모달 전용 화면


/* app/modal.tsx */
import { Link } from 'expo-router';
import { StyleSheet } from 'react-native';

import { ThemedText } from '@/components/themed-text';
import { ThemedView } from '@/components/themed-view';

export default function ModalScreen() {
  return (
    <ThemedView style={styles.container}>
      <ThemedText type="title">This is a modal</ThemedText>
      <Link href="/" dismissTo style={styles.link}>
        <ThemedText type="link">Go to home screen</ThemedText>
      </Link>
    </ThemedView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    padding: 20,
  },
  link: {
    marginTop: 15,
    paddingVertical: 15,
  },
});

(modal) 폴더로 묶어서 쓰는 패턴도 자주 사용함


app/
  _layout.tsx
  (tabs)/
    _layout.tsx
    index.tsx
  (modal)/
    _layout.tsx   // 여기서 presentation: "modal" 그룹 처리
    settings.tsx

FormSheet 모달 옵션 설정


import { Stack } from 'expo-router';
import { View, Button } from 'react-native';

function Layout() {
  return (
    <Stack>
      {/* 기본 메인 화면(index.tsx) 라우트 */}
      <Stack.Screen name="index" />

      <Stack.Screen
        name="modal"
        options={{
          /* 모달을 어떤 스타일로 띄울지 결정 (iOS에서 formSheet 형태로 표시됨) */
          presentation: 'formSheet',

          /* sheet(바텀시트)가 가질 수 있는 높이 단계(detent) 목록 (0~1 비율) */
          sheetAllowedDetents: [0.25, 0.5, 1],

          /* 처음 모달이 열릴 때 시작할 detent 단계 인덱스 (0이면 0.25부터 시작) */
          sheetInitialDetentIndex: 0,

          /* 상단에 드래그 가능한 grabber(손잡이)를 표시할지 여부 */
          sheetGrabberVisible: true,

          /* sheet 모서리 둥글기 값 (px 단위) */
          sheetCornerRadius: 24,

          /* sheet가 확장될 때 dim(배경 어두워짐)이 적용되지 않는 최대 detent 인덱스 */
          /* 예: 1이면 0.5 단계까지는 배경이 안 어두워지고, 그 이상부터 dim 적용 */
          sheetLargestUndimmedDetentIndex: 1,

          /* 푸터 추가 (sheet 하단에 고정되는 footer UI 영역) */
          unstable_sheetFooter: () => (
            <View style={{ padding: 16, backgroundColor: 'white' }}>
              <Button title="Confirm" onPress={() => {}} />
            </View>
          ),
        }}
      />
    </Stack>
  );
}

export default Layout;

🛖 API Routes (Web 전용)

API Routes

Web(Server output)에서만 동작하는 서버 엔드포인트이다.

API Routes(서버 엔드포인트): app폴더 안에서 서버 코드

app/ 폴더 안에서 +api.ts 확장자 파일을 만들면 그 경로가 서버 엔드포인트가 된다. (Next.js app/**/route.ts와 비슷한 개념)


// app/hello+api.ts  -> GET /hello
export async function GET(request: Request) {
  return Response.json({ hello: 'world' });
}

// 동적·중첩도 동일 규칙
// app/users/[id]/profile+api.ts -> /users/:id/profile
export async function POST(request: Request) {
  const body = await request.json();
  return Response.json({ ok: true, body });
}

API Routes를 위한 서버 번들기


/* app.json */
{
  "expo": {
    "web": {
      "output": "server"
    }
  }
}

🛖 nativewind v5

nativewind installation

Working package.json Dependencies


{
  "main": "expo-router/entry",
  "dependencies": {
    "expo": "~54.0.33",
    "nativewind": "^5.0.0",
    "react-native-css": "latest",
    "react-native-reanimated": "~4.1.1",
    "react-native-safe-area-context": "~5.6.0",
    "react-native-worklets": "0.5.1"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4.1.18",
    "postcss": "^8.5.6",
    "tailwindcss": "^4.1.18",
  },
  "pnpm": {
    "overrides": {
      "lightningcss": "1.30.1"
    }
  },
  "private": true
}

babel.config.js


module.exports = function (api) {
  api.cache(true);

  return {
    presets: ['babel-preset-expo'],
    plugins: [
      'react-native-reanimated/plugin',
    ],
  };
};

metro.config.ts


// Learn more <https://docs.expo.io/guides/customizing-metro>
const { getDefaultConfig } = require('expo/metro-config');
const { withNativewind } = require('nativewind/metro');

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);

module.exports = withNativewind(config);

postcss.config.mjs


export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

nativewind-env.d.ts


// @ts-ignore
/// <reference types="react-native-css/types" />

global.css


@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/preflight.css' layer(base);
@import 'tailwindcss/utilities.css';

@import 'nativewind/theme';

app/_layout.tsx


import '../global.css';

uniwind라는 것도 있음

🛖 svg를 컴포넌트로 사용하기

expo svg

svg 파일을 React 컴포넌트처럼 import하여 사용할 수 있도록 설정


# 설치
pnpm add react-native-svg
pnpm add -D react-native-svg-transformer

# nativewind 최신 버전과 충돌 → 5.0.0-preview.2로 고정
# pnpm i nativewind@5.0.0-preview.2

metro.config.js


// Learn more <https://docs.expo.io/guides/customizing-metro>
const { getDefaultConfig } = require('expo/metro-config');
const { withNativewind } = require('nativewind/metro');

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);

config.transformer.babelTransformerPath = require.resolve(
  "react-native-svg-transformer"
);
config.resolver.assetExts = config.resolver.assetExts.filter(
  (ext) => ext !== "svg"
);
config.resolver.sourceExts.push("svg");

module.exports = withNativewind(config);

global.d.ts


declare module "*.svg" {
  import * as React from "react";
  import { SvgProps } from "react-native-svg";
  const content: React.FC<SvgProps>;
  export default content;
}

🛖 font

expo-font

app.json


"plugins": [
  "expo-router",
    ...
  [
    "expo-font",
    {
      "fonts": [
        "./assets/fonts/PretendardVariable.ttf"
      ]
    }
  ]
],

사용하는 곳


/* components/ui/text.tsx */
import { Text as RNText, TextProps } from "react-native";

export function Text({ style, ...props }: TextProps) {
  return (
    <RNText
      {...props}
      style={[{ fontFamily: "PretendardVariable" }, style]}
    />
  );
}

useFonts 훅으로 로드가 되었는지 확인도 가능하다.


const [loaded, error] = useFonts({
  'Inter-Black': require('./assets/fonts/Inter-Black.otf'),
});

React-Native

[RN] 🛖 React Native with Expo (SDK 54) 사용법 — Router, Modal, API Routes, NativeWind v5 설정

▷ Expo 사용법 (sdk 54)

🛖 Routing

🛖 Route Group

🛖 Screen Routing (ft. useLocalSearchParams)

🛖 modal

🛖 API Routes (Web 전용)

🛖 nativewind v5

🛖 svg를 컴포넌트로 사용하기

🛖 font

[Next] 💠 Next.js 16 업데이트 정리

[Next] 💠 Next.js 사용법 (v15)

[RN] 🪅 patch-package로 node_modules 커스텀하기

[RN] 🛖 React Native with Expo (SDK 54) 사용법 — Router, Modal, API Routes, NativeWind v5 설정

▷ Expo 사용법 (sdk 54)

🛖 Routing

🛖 Route Group

🛖 Screen Routing (ft. useLocalSearchParams)

🛖 modal

🛖 API Routes (Web 전용)

🛖 nativewind v5

🛖 svg를 컴포넌트로 사용하기

🛖 font