【入門編】 @importによる外部型定義のインポート – JavaScript実践ガイド

こんにちは！フロントエンドの現場を渡り歩いてきた、チーフアーキテクトの私です。

JavaScriptを書いていると、「あれ、このデータってなんだっけ？」と迷子になったり、他のファイルで作ったデータ構造を何度も書き直してうんざりしたりした経験はありませんか？「TypeScriptにするほど大げさなプロジェクトじゃないけれど、もう少しコードの設計をきれいに保ちたい……」そんなモヤモヤを抱えているあなたにこそ知ってほしい、とっておきの裏技があります。

それが、今回お話しするJSDocの `@import` による外部型定義のインポートです。

難しそうな言葉が並びましたが、大丈夫ですよ。一つひとつ、身近な例えを交えながら優しく紐解いていきましょう！

—

1. なぜ「型」の話が必要なの？（お買い物のレシートに例えて）

突然ですが、スーパーでお買い物をしたときのことを想像してください。
カゴの中身をレジ袋に詰めるとき、店員さんは「これは野菜、これはお惣菜、これは洗剤」と、ちゃんと言葉が書かれたラベルや仕切りを使って整理してくれますよね。もし、すべてがぐちゃぐちゃに混ざっていたら……お会計のときも、家に帰って冷蔵庫にしまうときも大パニックです。

JavaScriptの「データ型」もこれと全く同じです。
変数や関数のなかに「文字」が入るのか、「数字」が入るのか、それとも「名前や年齢がまとまった複雑なデータ（オブジェクト）」が入るのか。これをあらかじめ決めておかないと、プログラムという巨大なレジスターの前でエラーが起きてしまいます。

特に、チームでの開発や、少し規模が大きくなったWeb制作の現場では、「データの設計図（型定義）」を共有することが、バグを防ぐ一番の特効薬になるんです。

—

2. JSDocってなに？ JavaScriptの「付箋」文化

「でも、JavaScriptってTypeScriptみたいに厳格な型書きができないじゃん？」と思いました？
そこで登場するのが JSDoc（ジェイエスドック） です。

JSDocは、JavaScriptのコードの中に `/ … /` という特別なコメント（付箋）を書いて、そこに「この関数はこういうデータを受け取りますよ」とメモを残せる仕組みです。

例えば、こんな感じです。

ユーザーの名前を表示する関数
@param {string} name – ユーザーの名前（文字列）

/
function showUserName(name) {
console.log(“こんにちは、” + name + “さん！”);
}

これだけでも、エディタ（VS Codeなど）が「あ、ここは文字（string）を入れなきゃいけないんだな」と察知して、間違った値を入れようとすると赤く波線を出して怒ってくれるようになります。すごく便利ですよね！

—

3. 本題： `@import` で「設計図のコピー＆ペースト」から卒業する

さて、ここからが今日の本番です。

プロジェクトが大きくなってくると、色々なファイルで「ユーザーのデータ構造」や「お買い物の商品データ構造」を何度も何度も書き直すようになります。
「あ、ユーザーの住所（address）という項目が増えた！全部のファイルのJSDocを書き直さなきゃ……！」

……そんな面倒な作業、プロのエンジニアは絶対にやりません。
ここで活躍するのが、`@import`（外部からの型定義のインポート） です。

イメージとしては、「会社の総務部が一括管理している『社員名簿のテンプレート』を、各部署のデスクにコピーして共有する」ような感覚です。一つのファイルを直せば、プロジェクト全体の型が自動的に最新にアップデートされます。

実践！コードを見てみよう

実際にどう書くのか、シンプルな例で見ていきましょう。

まずは、型定義（設計図）だけを書いたファイルを用意します。
拡張子は普通の `.js` で大丈夫です。

// types.js （型定義だけをまとめたファイル）

@typedef {Object} User
@property {number} id – ユーザーID
@property {string} name – ユーザーの名前
@property {string} email – メールアドレス

// このファイルを他のファイルから使えるように、空のオブジェクトをエクスポートしておきます
export {};

お疲れ様です！これが「社員名簿のテンプレート」です。
では、実際にこのテンプレートを別のファイルで読み込んで（インポートして）使ってみましょう。

// userController.js （実際の処理を書くファイル）

@import { User } from ‘./types.js’

ユーザー情報をコンソールに表示する関数
@param {User} user – さっきインポートしたUser型を指定！

/
function printUserInfo(user) {
// VS Codeなどのエディタが、user. と打つだけで id, name, email をサジェストしてくれます
console.log(`ID: ${user.id}, 名前: ${user.name}`);
}

// 実際に使ってみる
const tanaka = {
id: 1,
name: “田中太郎”,
email: “tanaka@example.com”
};

printUserInfo(tanaka);

見てください、このスッキリとしたコードを！
`userController.js` の上部にある、

@import { User } from ‘./types.js’

この1行が魔法の呪文です。これで、`types.js` で定義した `User` という設計図を、そのままこのファイルに持ち込むことができました。

—

4. 初学者がつまずきやすいポイントと優しいフォロー

新しい技術に触れるとき、誰もが一度は「あれ？」と手が止まるポイントがあります。ここで先回りして安心材料をお渡ししておきますね。

つまずきポイント1：「動かないんだけど……エラーが出る！」

原因の多くは： パス（ファイルの場所）の指定ミスです。`./types.js` や `../components/types.js` など、自分のファイルから見て型定義ファイルがどこにあるのか、フォルダの階層を確認してみてください。
チーフからのアドバイス： 最初はパスの指定でよく迷子になります。エディタのファイル補完機能を上手に使って、ファイル名が正しく入力されているか確認しましょう。

つまずきポイント2：「JavaScriptなのに、なんでわざわざファイルを分けるの？」

原因の多くは： 小さなコードを書いているうちは、1つのファイルに全部書いたほうが楽に感じるからです。
チーフからのアドバイス： 大丈夫、今はそのままで完璧です！ただ、コードが100行、200行と増えてきて「あれ、どこに何を書いたっけ？」となったときが、この `@import` を思い出す最高のタイミングです。未来の自分のために、そっと引き出しにしまっておいてください。

—

さいごに

今回は、JSDocの `@import` を使った外部型定義のインポートについてお話しました。

TypeScriptという高い山にいきなり登らなくても、使い慣れたJavaScriptのままで、JSDocと `@import` を組み合わせれば、驚くほど快適で堅牢な開発環境を手に入れることができます。

「コードを書くのがもっと楽しくなった！」
そんな風に感じてもらえたら、チーフアーキテクトとしてこれ以上嬉しいことはありません。

今日も明日も、あなたの楽しいコーディングライフを応援しています！それではまた、別の現場でお会いしましょう。