Appearance
制作環境
エディタ
Visual Studio Codeを推奨します。
また、コーディング時の自動修正・自動警告を有効にするために以下のプラグインをインストールしてください。
他のエディタを利用して構いませんが、次のようなエディタの使用は原則として禁止します。
- 改行コードを変更できない
- 不可視文字を表示できない
- 検索・置換機能がない
推奨エディタ以外の利用に関して、なにかトラブルがあった際の原因がエディタによるものである場合の対応に時間がかかる可能性があることは留意してください。
制作環境の準備
次の環境をPCのローカルに準備する必要があります。
- git
- Node.js
- yarn
Node.jsとyarnはプロジェクトによってバージョンを切り替える必要があるため、バージョン管理ツールを利用してインストールしてください。 管理ツールはVoltaを推奨します。Voltaのセットアップ手順を参考に整備してください。
プロジェクトのpackage.jsonにvoltaフィールドとpackageManagerフィールドが設定されている場合、Voltaが自動的に適切なバージョンに切り替えます。これらのフィールドに記載されているバージョンを参照してください。
Gitのインストール
基本的に方法は問いません。 macOSの場合、通常初めてgitコマンドを利用するとXCodeのライセンスに同意する必要があったり、XCodeそのものをインストールする必要があります。 XCodeをどうしてもインストールできない場合、Gitの本家からインストーラを使ってインストールしても構いません。
初期ファイルの準備
現在整備中です
以下は開発中のため、初期ファイルの準備はSlackから@systemにリクエストしてください。
空のリポジトリで次のパッケージを実行します。
zsh
npx @d-zero/create-frontend開発に必要なpackage.jsonやコンフィグファイル、サイト構造の初期ファイルが展開されます。
開発ソースコードと製品ソースコード
HTML/CSS/JavaScriptなどのコードは、開発ソースコードと製品ソースコードに分かれます。
📂
├── 📂 __assets/
│ ├── 📂 htdocs/
│ │ └── index.pug
│ │ ├── 📂 sub-dir/
│ │ │ ├── index.pug
│ │ │ └── sub-page.pug
│ │ ├── 📂 css/
│ │ │ └── style.css
│ │ └── 📂 js/
│ │ └── script.js
│ └ 📂 _libs/
└── 📂 htdocs/
├── index.html
├── 📂 sub-dir/
│ ├── index.html
│ └── sub-page.html
├── 📂 css/
│ └── style.css
└── 📂 js/
└── script.js__assetsフォルダ配下が開発ソースコード、htdocsフォルダ配下が製品ソースコードとなります。
ドキュメントルート
htdocsフォルダとその中のファイルを最終的にウェブサーバーにアップロードすることになります。 htdocsはドキュメントルートにあたります。 プロジェクトによっては名前を変更しても構いません。 その場合、ビルド設定を変更する必要があります。
製品ソースコードの改変
開発環境のビルドツールによって、開発ソースコードから製品ソースコードに変換がされるため、製品ソースコードを手動で編集・改変することは原則避けてください。
製品ソースコードを納品後にクライアントの手で変更があるケースなどは別途体制などを検討し、プロジェクト個別で対応します。
各開発ソースコードは、次のプリプロセッサやトランスパイラ・ビルドツールを通して製品ソースコードに変換されます。
| 対象 | プリプロセッサ/トランスパイラ/ビルドツール |
|---|---|
| HTML | Pug / Kamado |
| CSS | PostCSS(Autoprefixer 他) / PostCSS |
| JavaScript | TypeScript / esbuild |
HTMLはHTMLとPugどちらの言語でも記述ができます。 CSSはPostCSSのみとなっており、JavaScriptはTypeScriptもしくは最新のECMAScriptのどちらにも対応しています。 それぞれの対応する具体的なバージョンはpackage.jsonや各種コンフィグファイルを参照してください。
ビルド方法
プロジェクト開始時は、そのプロジェクトで利用するパッケージを次のコマンドでインストールしてください。
zsh
yarn installNode.jsとyarnのバージョン切り替え
package.jsonに設定されているvoltaフィールドとpackageManagerフィールドの値によって自動的にバージョンが切り替わります。 Volta以外のバージョン管理ツールを利用している場合は、そのツールの設定に従ってバージョンを切り替えてください。
ビルド方法
yarnのスクリプトコマンドを使ってビルドをします。
zsh
yarn [オプション]次のコマンドで動作するようにpackage.jsonに設定されています。
| コマンド | 動作 |
|---|---|
yarn build | 全リソースファイルのコンパイルとリントチェック・バリデーションを行います。内部でkamado buildを実行します。 |
yarn build:only | リントチェックをスキップしてビルドのみを実行します。内部でkamado buildを実行します。引数を渡すことで特定のファイルやパターンのみをビルドできます。 |
yarn dev | ローカルサーバーを立ち上げます。内部でkamado devを実行します。開発サーバーのポート番号はkamado.config.tsのdevServer.portで設定されています。yarn dでも同様に動作します。 |
yarn lint | すべてのリントチェックを実行します。 |
yarn lint:html | HTMLとPugファイルに対してMarkuplintを実行します。 |
yarn lint:pug | Pugファイルに対してpug-lintを実行します。 |
yarn lint:css | CSSファイルに対してStylelintを実行します。自動修正も行います。 |
yarn lint:js | JavaScriptとTypeScriptファイルに対してESLintを実行します。自動修正も行います。 |
yarn lint:ts | TypeScriptの型チェックを実行します。 |
yarn lint:format | Prettierによるコードフォーマットを実行します。 |
yarn lint:spell | cspellによるスペルチェックを実行します。 |
yarn lint:text | HTMLとPugファイルに対してtextlintを実行します。 |
yarn d | yarn devのエイリアスです。 |
yarn bge | @burger-editor/localを使用してBurgerEditorのローカルサーバーを起動します。HTMLファイルを直接編集できるローカル開発環境を提供します。設定はburgereditor.config.jsで行います。 |
yarn print | @d-zero/printを使用してウェブページのスクリーンショットを撮影し、メモ欄付きのPDFファイルを生成します。__info/print.txtファイルからURLリストを読み込みます。 |
yarn update | 依存パッケージのインタラクティブなアップデートを行います。 |
yarn test | Vitestによるテストを実行します。 |
特定のファイルのみをビルド
yarn build:onlyに引数を渡すことで、特定のファイルやパターンのみをビルドできます。
zsh
yarn build:only __assets/htdocs/__tmpl/000_home.pug
yarn build:only "__assets/htdocs/__tmpl/*.pug"
yarn build:only "__assets/htdocs/**/*.css"
yarn build:only "__assets/htdocs/**/*.ts"--verboseフラグを追加すると、詳細なログが出力されます。
zsh
yarn build:only __assets/htdocs/__tmpl/000_home.pug --verboseKamadoの開発サーバーはオンデマンドビルド方式を採用しています。ブラウザでアクセスしたページがリクエスト時に自動的にビルドされます。ファイル監視は行わず、ブラウザのリロードによるサーバーリクエストのみがビルドのトリガーとなります。
開発サーバーのポート番号はkamado.config.tsのdevServer.portで設定されています。デフォルトのポート番号は設定ファイルを参照してください。
主なコーディング手順
yarn devでローカルサーバーを立ち上げる- その状態でコーディングをする
- 一連の作業が終わったら
yarn buildで全体をチェックし製品ソースコードを生成する - コミットする
Gitの対象ファイル
現状、テストサーバーのビルド環境の整備不足のため、htdocsフォルダ配下のファイルは.gitignoreに含まれておらずコミットの対象です。
yarn devコマンドの注意点
yarn devでは一時ファイルが製品ソースコード側に生成されることがあります。コミットの際は必ずyarn buildをしてください。
治外法権ディレクトリ
クライアントや他ベンダーの制作したソースコードと共存させる場合、開発ソースコードの中ではリンターなどから除外するためにextraterritorialを作っています。
__assets/htdocs/のPugやCSS、JavaScriptは、それぞれincludeや@import、importを使ってextraterritorialディレクトリのソースコードを読み込み、製品ソースコードに反映させてください。
extraterritorialディレクトリの利用にあたって
あくまでも社内の責任の範囲の外にあるソースコードを共存させるものなので、社内で責任を持ち管理する必要があるコードに関してはこのディレクトリ内で管理しないでください。
プロジェクト固有の規定がある場合は、リンターの側の設定を変えて、extraterritorialディレクトリは使わないようにしてください。