静的ウェブサイトを開発するためのボイラープレート
Switch branches/tags
Nothing to show
Clone or download

README.md

Real world website boilerplate

静的ウェブサイトを開発するためのボイラープレートです。次のような特徴があります。

目次

推奨環境

  • Mac OS X または Windows
  • Yarn
  • Node.js 8.9 以降
  • EditorConfig および Prettier をサポートするエディタ

導入

  1. 最新版のボイラープレートを取得

    git clone https://github.com/yuheiy/real-world-website-boilerplate.git my-project/
    cd my-project/
    rm -rf .git/
  2. yarn installを実行して依存パッケージのインストール

  3. yarn startを実行して開発用サーバーの起動

本番用ビルド

次のコマンドによって本番用ビルドを実行します。

yarn build

これによってdist/ディレクトリにビルドされたファイルが生成されます。

ディレクトリ構造

.
├── dist/
│   └── path/to/project/
│       ├── assets/
│       │   ├── css/
│       │   │   └── main.bundle.css
│       │   ├── img/
│       │   │   └── logo.svg
│       │   └── js/
│       │       └── main.bundle.js
│       ├── about.html
│       ├── index.html
│       └── pub.html
├── public/
│   ├── assets/
│   │   └── img/
│   │       └── logo.svg
│   └── pub.html
├── src/
│   ├── css/
│   │   └── main.scss
│   ├── html/
│   │   ├── _data/
│   │   │   └── meta.yml
│   │   ├── about.pug
│   │   ├── about.yml
│   │   ├── index.pug
│   │   └── index.yml
│   └── js/
│       └── main.js
├── vendor-public/
│   └── common.css
├── task/
├── tmp/
│   └── path/to/project/
│       └── assets/
│           ├── css/
│           │   ├── main.bundle.css
│           │   └── main.bundle.css.map
│           └── js/
│               ├── main.bundle.js
│               └── main.bundle.js.map
├── package.json
└── realworld.config.js

サブディレクトリが設定されていない場合、ファイルはdist/ディレクトリあるいはtmp/ディレクトリの直下に生成されます。サブディレクトリが設定されている場合、それらのディレクトリを基準として、指定されたサブディレクトリにファイルが生成されます。

サブディレクトリの設定方法はrealworld.config.jsファイルを参照してください。

dist/ディレクトリ

yarn buildによって本番用ビルドが実行されたときに、このディレクトリにファイルが生成されます。

src/ディレクトリのファイルはコンパイル後に生成され、public/ディレクトリのファイルはそのままコピーされます。vendor-public/ディレクトリのファイルは無視されます。

public/ディレクトリ

コンパイルが不要な静的ファイルをこのディレクトリに配置します。/または指定されたサブディレクトリから、このディレクトリを参照できます。

src/ディレクトリ

コンパイルをソースファイルをこのディレクトリに配置します。主にこのディレクトリで作業することになるでしょう。

CSS はsrc/css/main.scssファイルが、アセットディレクトリのcss/main.bundle.cssファイルとして生成されます。

JavaScript はsrc/js/main.jsファイルが、アセットディレクトリのjs/main.bundle.jsファイルとして生成されます。

vendor-public/ディレクトリ

コンパイルが不要かつ納品をしないファイルを配置します。本番用ビルド時にdist/ディレクトリに含まれません。

サブディレクトリの設定に関わらず/から参照できます。

サイトの下層ページを制作する場合に、共通で読み込む必要のある CSS ファイルなどを配置することを想定しています。

task/ディレクトリ

ビルドタスクに関するファイルを配置します。

tmp/ディレクトリ

yarn startによって開発サーバーが起動されたときに、開発に必要な一時ファイルが生成されます。

realworld.config.jsファイル

プロジェクトの URL を設定します。

  • サブディレクトリを設定しない場合は次のようにします。

    module.exports = {
      origin: 'http://example.com',
    }
  • サブディレクトリを設定する場合は次のようにします。

    module.exports = {
      origin: 'http://example.com',
      subdir: 'path/to/project',
    }

HTML テンプレート

テンプレートエンジンとして Pug を採用しています。

開発時には、リクエストされたパスと対応するファイルのみをコンパイルすることによって、全体のページ数と比例してビルド時間が増大することを防止しています。Browsersync のミドルウェアとしてreal-world-website-render-helperを利用することによって実現しています。

src/html/ディレクトリのファイルは、ディレクトリ構造を維持したまま HTML ファイルとして出力されます。src/html/index.pugの場合、/index.htmlから参照できます。_から始まるファイル及びディレクトリは、個別に HTML ファイルとして出力されません。

file(全ページ共有データ)

src/html/_data/ディレクトリ直下に YAML ファイルまたは JSON ファイルを作成することで、file変数として対応付けされ、全てのページから参照できるようになります。src/html/_data/meta.ymlというファイルの場合、file.metaから参照できます。

page(個別ページ用データ)

Pug ファイルと同名の YAML ファイルまたは JSON ファイルを作成することで、対応するファイルのみで有効になるデータを設定できます。src/html/page.pugというファイルで利用するデータを指定する場合、src/html/page.ymlというファイルを作成します。

自動的にpage.pathにページのパスが設定されます。src/html/page.pugの場合は/page.htmlになり、src/html/index.pugの場合は省略されて/になります。absPath()などの関数と組み合わせることで、サブディレクトリにも対応したパスを出力できます。

origin

realworld.config.jsに設定したoriginの値を参照できます。

absPath(pagePath)

指定されたサブディレクトリを基準とした相対パスを、絶対パスに変換します。サブディレクトリとしてpath/to/projectが指定されていた場合、absPath('page.html')/path/to/project/page.htmlになります。

assetPath(filePath)

アセットディレクトリを基準とした相対パスを、絶対パスに変換します。assetPath('img/logo.svg')/assets/img/logo.svgになります。

absUrl(pagePath)

指定されたサブディレクトリを基準とした相対パスを、絶対 URL に変換します。originhttp://example.comが指定されていた場合、absUrl('page.html')http://example.com/page.htmlになります。

assetUrl(filePath)

アセットディレクトリを基準とした相対パスを、絶対 URL に変換します。originhttp://example.comが指定されていた場合、assetUrl('img/logo.svg')http://example.com/assets/img/logo.svgになります。

__DEV__

yarn startでの開発時はtrueになり、yarn buildでのビルド時はfalseになります。

対象ブラウザ

ビルドの対象にするブラウザは.browserslistrcで設定します。記述方法はBrowserslist のドキュメントを参照してください。

デフォルトでは次のようになっています。

last 1 Chrome version
last 1 ChromeAndroid version
last 1 Edge version
last 1 Firefox version
last 1 iOS version
last 1 Safari version
> 3% in JP

この設定は次のパッケージから参照されます。

なお、IE10 以下を対象とする場合、Babel で問題が発生することがあります

レシピ

CSS ファイルのエントリーポイントの設定

gulpfile.jsを編集して CSS ファイルのエントリーポイントを変更できます。デフォルトではsrc/css/main.scssがアセットディレクトリにcss/main.bundle.cssとして出力されます。

const cssEntries = {
  main: 'src/css/main.scss',
}

オブジェクトのキーが出力されるファイル名、対応する値がソースファイルのパスです。

src/css/print.scssをエントリーポイントとして追加したい場合、次のように設定します。アセットディレクトリにcss/print.bundle.cssとして出力されます。

const cssEntries = {
  main: 'src/css/main.scss',
  print: 'src/css/print.scss',
}

アセットディレクトリの変更

task/util.jsを編集することでアセットディレクトリを変更することができます。

  • デフォルトでは、プロジェクトディレクトリ直下のassets/ディレクトリが設定されています。

    const assetPath = path.join(basePath, 'assets')
  • プロジェクトディレクトリ直下に配置する場合は、次のように変更します。

    const assetPath = basePath
  • サブディレクトリとしてpath/to/projectが指定されており、/assets/path/to/projectというディレクトリに配置する場合は、次のように変更します。

    const assetPath = join('/assets', basePath)
  • https://assets-cdn.example.comという別オリジンから配信する場合は、次のように変更します。

    -const baseAssetUrl = `${origin}${toPosixPath(assetPath)}`
    +const baseAssetUrl = 'https://assets-cdn.example.com'

    加えて、HTML テンプレートではassetPath()を利用せず、assetUrl()のみを利用するようにします。task/renderHtml.jsは次のように変更します。

    const baseLocals = {
      __DEV__: !isProd,
      origin,
      absPath: (pagePath = '') => toPosixPath(join(basePath, pagePath)),
    - assetPath: (filePath = '') => toPosixPath(join(assetPath, filePath)),
      absUrl: (pagePath = '') => `${baseUrl}${toPosixPath(join('/', pagePath))}`,
    + assetUrl: isProd
    +   ? (filePath = '') => `${baseAssetUrl}${toPosixPath(join('/', filePath))}`
    +   : (filePath = '') => toPosixPath(join(assetPath, '/', filePath)),
    }

    デプロイ時は、ビルドによって生成されたアセットディレクトリ以下のファイルを CDN にアップロードしてください。

Server Side Includes の設定

Browsersync のオプションであるrewriteRulesを設定することで有効になります。読み込む対象のファイルをvendor-public/ディレクトリに配置する場合、gulpfile.jsを次のように変更します。

const serve = (done) => {
  const { existsSync, statSync, readFileSync } = require('fs')

  bs.init(
    {
      // 省略
      rewriteRules: [
        {
          match: /<!--#include virtual="(.+?)" -->/g,
          fn(_req, _res, _match, filePath) {
            const srcFilePath = join('vendor-public', filePath)

            if (existsSync(srcFilePath) && statSync(srcFilePath).isFile()) {
              return readFileSync(srcFilePath, 'utf8')
            } else {
              return `<strong style="color: red">\`${srcFilePath}\` could not be found</strong>`
            }
          },
        },
      ],
      // 省略
    },
    done,
  )
}

これによって次のようなディレクティブが利用できるようになります。

<body>
  <!--#include virtual="/includes/site-header.html" -->
  <main>
    ...
  </main>
  <!--#include virtual="/includes/site-footer.html" -->
</body>

差分納品ファイル管理ガイド

納品ファイルの差分管理が必要な場合、dist/ディレクトリを Git にコミットするようにします。.gitignoreを次のように変更します。

node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

-/dist/
/tmp/

リリースの毎にyarn buildを実行して、生成されるdist/ディレクトリを Git にコミットします。このコミットに、Git のタグを付けておくと参照しやすくなります。

前回のリリースと対応するコミットがrelease-20180101の場合、次のコマンドで追加・変更したファイルのみを Zip ファイルとして生成できます。

git archive --format=zip --prefix=htdocs/ HEAD:dist `git diff --diff-filter=ACMR --name-only release-20180101 HEAD | grep "^dist/" | sed -e "s/dist\///"` > htdocs.zip

削除したファイルリストは次のコマンドで生成できます。

git diff release-20180101 --name-only --diff-filter=D | grep "^dist" | sed -e "s/dist\///" > deleted-files.txt