jQuery 플러그인 사용 시 발생하는 TypeError: $(...).xxx is not a function 오류 해결 방법

jQuery를 사용하다 보면 다음과 같은 오류 메시지를 자주 보게 됩니다.

 

 

 

"Uncaught TypeError: $(...).datepicker is not a function"

또는

"Uncaught TypeError: $(...).modal is not a function"
"Uncaught TypeError: $(...).select2 is not a function"

 

형태만 다를 뿐 모두 같은 종류의 오류입니다.
브라우저 입장에서는 $(...).datepicker 라는 함수를 호출했는데,
datepicker라는 함수가 존재하지 않기 때문에
"function이 아니다"라는 에러를 출력하는 것입니다.

이 글에서는 이 오류가 발생하는 대표적인 경우와
실무에서 바로 적용할 수 있는 해결 방법을 정리해 보겠습니다.

 

1. 오류의 의미 이해하기

오류 메시지를 분해해서 보면 다음과 같습니다.

• TypeError
  자료형 관련 오류입니다. 함수가 아니거나, 호출할 수 없는 대상을 함수처럼 호출했을 때 발생합니다.
• $(...).datepicker is not a function
  $(...) 까지는 잘 동작했지만, 그 결과에 대해 .datepicker 함수를 호출하려고 하니
  해당 메서드가 전혀 등록되어 있지 않다는 뜻입니다.

즉, jQuery는 살아 있는데
해당 플러그인의 "메서드"가 등록되지 않은 상태라고 보시면 됩니다.

 

2. 가장 흔한 원인 1 ― jQuery 플러그인 파일이 로드되지 않은 경우

가장 먼저 확인해야 할 부분은
datepicker, select2, modal 등 플러그인 스크립트 자체가 로딩되었는지 여부입니다.

예를 들어 datepicker를 사용하고 싶어 아래와 같이 작성했다고 가정해 보겠습니다.

<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script>
  $('#startDate').datepicker();   // 오류 발생 가능
</script>

 

이 상태에서는 jQuery만 로딩된 것이지,
datepicker 플러그인은 전혀 포함되지 않은 상태입니다.

※ 해결 방법
datepicker 플러그인을 제공하는 JS 파일을 먼저 포함해 주셔야 합니다.

예시 (jQuery UI datepicker 기준):

<link rel="stylesheet" href="https://code.jquery.com/ui/1.13.3/themes/base/jquery-ui.css">
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.3/jquery-ui.min.js"></script>

<script>
  $(function(){
    $('#startDate').datepicker();
  });
</script>

핵심 포인트는 다음 두 가지입니다.

• 플러그인 JS 파일(jquery-ui.min.js)을 반드시 포함할 것
• jQuery보다 뒤에 로딩할 것

 

3. 가장 흔한 원인 2 ― 로딩 순서가 잘못된 경우

jQuery 플러그인은 대부분 다음과 같은 구조를 가정합니다.

1. jQuery가 먼저 로딩
2. 그 다음 플러그인(JS)이 로딩
3. 마지막에 실제 사용 코드 실행

아래처럼 순서가 뒤집히면 오류가 발생합니다.

 

<script src="/js/jquery-ui.min.js"></script>
<script src="/js/jquery-3.7.1.min.js"></script>

<script>
  $('#startDate').datepicker();   // 여기서 $(...).datepicker is not a function
</script>

 

이 경우 jQuery UI가 로딩될 때
아직 jQuery가 전역에 등록되어 있지 않으므로
datepicker 메서드 등록에 실패하게 됩니다.

※ 해결 방법
항상 jQuery를 가장 먼저, 그 다음에 플러그인을 로딩해 주셔야 합니다.

 

<script src="/js/jquery-3.7.1.min.js"></script>
<script src="/js/jquery-ui.min.js"></script>

<script>
  $('#startDate').datepicker();   // 정상 동작
</script>

 

 

4. 플러그인 CSS를 빼먹은 경우 (동작은 하지만 화면에 안 보이는 케이스)

이 경우에는 오류 메시지는 안 뜨지만,
사용자 입장에서는 "안 되는 것처럼 보이는" 상황이 발생합니다.

예를 들어 datepicker는 JS 파일만으로는 충분하지 않고
CSS 파일도 함께 포함해야 제대로 된 UI가 나타납니다.

 

<link rel="stylesheet" href="https://code.jquery.com/ui/1.13.3/themes/base/jquery-ui.css">
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.3/jquery-ui.min.js"></script>

 

CSS를 포함하지 않으면

• 에러는 안 나는데
• 달력이 보이지 않거나 레이아웃이 깨져 보일 수 있습니다.

따라서 플러그인이 CSS도 제공하는 경우
JS + CSS를 한 세트로 생각하시는 것이 좋습니다.

 

 

5. $(선택자)가 비어 있는 경우와의 차이점

또 다른 흔한 오류로
Cannot read properties of null (reading '...') 같은 에러가 있습니다.
이것은 선택자에 해당하는 DOM 요소가 존재하지 않을 때 발생합니다.

반면

• $(...).datepicker is not a function
  → jQuery는 살아 있고, 선택자 결과도 존재하는데
  datepicker라는 메서드가 아예 등록되어 있지 않을 때 발생

둘을 구분해서 봐야 원인을 빠르게 찾을 수 있습니다.

 

 

6. CDN/로컬 혼용 시 주의사항

실무에서는 다음과 같은 혼용 환경에서 문제가 자주 발생합니다.

• 어떤 화면은 CDN 버전 jQuery
• 어떤 화면은 로컬 버전 jQuery
• 플러그인은 특정 화면에서만 로컬로 추가

이 과정에서 아래와 같은 실수가 많습니다.

• 플러그인 JS가 로딩되지 않는 페이지에서
  이전에 쓰던 코드를 그대로 복붙함
• 공통 레이아웃에는 jQuery만 넣고,
  일부 페이지에서만 플러그인 JS를 따로 넣는데 순서가 꼬임

이런 상황에서는 다음을 점검해 보시는 것이 좋습니다.

1. 해당 페이지의 HTML 소스에서
   jQuery와 플러그인 JS가 모두 포함되어 있는지
2. 포함되어 있다면, jQuery → 플러그인 순서로 로딩되는지
3. Network 탭에서 404, 500 오류는 없는지

 

※마무리 체크포인트

TypeError: $(...).xxx is not a function 오류가 발생했을 때
다음 네 가지를 순서대로 확인해 보시면 대부분 해결됩니다.

1. 플러그인 JS 파일이 실제로 포함되어 있는가
2. jQuery를 먼저, 플러그인을 나중에 로딩하고 있는가
3. 플러그인이 의존하는 CSS 파일까지 포함했는가
4. 다른 페이지에서 썼던 코드만 복사해 온 것은 아닌가 (환경이 다른지 확인)

 

모두 즐코딩하세요 !