안드로이드 태블릿에서 Next.js 프로젝트 실행하기
들어가기 앞서
이 문서는 안드로이드 태블릿에서 Termux + code-server(VS Code) 환경을 구성한 상태를 전제로, 해당 환경에서 Next.js 프로젝트를 생성하고 개발 서버를 실행하는 방법을 설명합니다.
PC가 아닌 태블릿 환경에서도 실제 웹 개발이 가능하다는 점을 확인하는 것이 목적입니다.
1. code-server 실행 및 터미널 열기
먼저 code-server를 실행합니다.
bashcode-server --auth none --host 0.0.0.0 --port 8080
code-server가 실행되면 VS Code Web 화면이 열립니다.
터미널은 아래 단축키로 열 수 있습니다.
터미널 단축키
- `Ctrl + `` (백틱)
단축키를 입력하면 아래와 같이 화면 하단에 터미널이 표시됩니다.
2. Node.js 설치하기
Next.js 실행을 위해 Node.js를 설치합니다.
bashpkg install nodejs-lts
LTS(Long Term Support) 버전을 설치하는 것이 가장 안정적입니다.
설치가 완료되면 아래와 같이 Node.js가 정상적으로 설치된 것을 확인할 수 있습니다.
예시) 작성 시점 기준 설치 버전: Node.js 24.11.1
3. Next.js 프로젝트 생성
웹 브라우저에서 Next.js 공식 사이트에 접속하면, 메인 화면에 프로젝트 생성 명령어가 안내되어 있습니다.
bashnpx create-next-app@latest
명령어를 실행하면 프로젝트 설정에 대한 질문이 순서대로 나타납니다.
이번 예제에서는 커스터마이징 설정을 선택하였으며, 선택한 항목은 아래와 같습니다.
plain프로젝트 이름은 무엇인가요? → my-app
Next.js 권장 설정을 사용할까요? → 아니오
TypeScript를 사용할까요? → 예
React Compiler(실험적 기능)를 사용할까요? → 아니오
Tailwind CSS를 사용할까요? → 예
소스 코드를 src/ 디렉토리 안에 둘까요? → 예
App Router를 사용할까요? → 예
import 경로 별칭을 커스터마이즈할까요? (기본: @/) → 아니오
설정이 완료되면 Next.js 프로젝트가 자동으로 생성됩니다.
4. Next.js 개발 서버 실행 (문제 해결 포함)
생성된 프로젝트 디렉토리로 이동한 뒤 개발 서버를 실행합니다.
bashcd ~/workspace/my-app
npm run dev
일반적인 PC 환경이라면 개발 서버가 바로 실행되지만, 안드로이드 태블릿 환경에서는 아래와 같은 오류가 발생할 수 있습니다.
오류 원인
Next.js 최신 버전은 기본적으로 Turbopack을 사용합니다.
그러나 Turbopack은 현재 안드로이드(ARM) 기반 Termux 환경을 완전히 지원하지 않기 때문에 개발 서버 실행 시 오류가 발생합니다.
해결 방법: Webpack 사용하도록 설정 변경
package.json 파일을 열어 scripts 항목을 아래와 같이 수정합니다.
json{
"scripts": {
"dev": "next dev --webpack",
"build": "next build --webpack",
"start": "next start --webpack",
"lint": "eslint"
}
}
--webpack 옵션을 명시적으로 지정하면, Turbopack 대신 Webpack을 사용하여 빌드 및 실행하게 됩니다.
수정 후 다시 개발 서버를 실행합니다.
bashnpm run dev
5. 실행 확인
개발 서버가 정상적으로 실행되면 터미널에 서버 주소가 출력됩니다.
웹 브라우저에서 해당 주소로 접속했을 때, 아래와 같은 기본 Next.js 화면이 표시되면 성공입니다.
마무리
이제 안드로이드 태블릿 환경에서도 Next.js 개발 서버를 실행할 수 있는 환경이 완성되었습니다.
다음 단계에서는:
- GitHub 저장소 연동
- 코드 푸시
- 배포 환경 구성
과정을 이어서 다뤄볼 예정입니다.