Quden Dev Doc

Appearance

Dev-doc: Quden Frontend ​

これは何？ ​

toruca の Web フロントエンド（Next.js）に関する開発ドキュメントです。 全体像は Quden アーキテクチャ を参照してください。

目次 ​

Keep in mind ​

アプリケーションのドメインは app.toruca.com にする予定です。

リソース ​

Dependencies ​

  • Docker

ローカルでの起動方法 ​

環境変数の準備 ​

GitHub ではシークレットを管理しないという原則に従い、シークレットの値は bitwarden で管理しています（バックエンドも同様です）。 bitwarden に frontend/.env.local というメモが作成してあるので、その値をコピーし、ローカルにファイル .env.local を手動で作成し、値を貼り付けてください。

追記（2023/10/25）: bitwardenの情報は古いです。repositoryにある .env.development に定義されている値をコピーして、 .env.localを追加してください。

plain
SENTRY_SERVER_INIT_PATH=XXXXXXXXXXXXXXXXXXXXXXXXXX
SENTRY_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXX

主な流れ ​

bash
# ローカルで docker コンテナを起動します
# http://localhost:3000 でアクセスできます
$ yarn dev:docker:up:https

ローカルは docker-compose を利用して起動しています。同じくローカルで起動している backend のネットワークに依存しているので、バックエンドを起動しておく必要があります。

yaml
# docker-compose.dev.yaml

# ...
networks:
  backend:
    external:
      name: "toruca-network" # これは、backend core API で作られるネットワークです

ローカルでバックエンド（toruca-core）のサーバーを立てている場合は、以下のデモユーザーでログインすることが可能です。

plain
EMAIL: test+0@toruca.com
PW: Password1234

ローカルでサーバーを立てない場合は、use-user 周りの設定を書き直すなどして、ログイン情報をごまかすなどする必要があります。

また、 /etc/hosts に以下のような記載を追加して、localhost に toruca ドメイン経由でアクセスするようにしてください。理由は、CDN (CloudFront) にアクセスする際に署名された cookie を利用するようにしており、その cookie は quden.io （開発時は dev.toruca.com）に対して発行されるためです。

bash
# /etc/hosts

# ... 既存の設定 ...

# For quden-dev
127.0.0.1 local.dev.quden.io

localhost の HTTPS 化をする ​

ローカルで開発する際、 http://localhost:3000/hoge のように HTTP 通信でアクセスすることが多いと思います。しかし、サーバーのレスポンスで set-cookie を使って、secure 属性を付与しつつ cookie をセットする場合、HTTP 環境下で開発しているとうまくいかない場合があります。

toruca のケースで言えば、動画データを CloudFront から取得する際に、cookie による署名の仕組みを利用しています。cookie を core サーバーからセットする際、Origin が HTTP だと、secure 属性を持つ cookie をブラウザに保持する事ができません。そこで、localhost の HTTPS 化が必要になります。

必要なアクションは以下の通りです。

  • 1: mkcert を使って、証明書をローカルで発行する
    • mkcertのインストールについてはこちらを参照：https://github.com/FiloSottile/mkcert
    • ローカルで
    • 例： $ mkcert local.dev.quden.io
    • 念の為、証明書は GitHub で管理しないつもりなので、各自がローカル環境で証明書を発行する必要があります
    • 例えば、 local.dev.quden.io で発行したなら、フロントとバックエンドの両方で同じ証明書が使えます
  • 2: 発行した証明書を secrets 配下に配置する

配置する場所は、フロント側とバックエンド側、それぞれ以下のとおりです。

bash
# --------
# フロント
# --------
# ...
/public
/secrets
  local.dev.quden.io-key.pem # プライベートキー
  local.dev.quden.io.pem # 公開鍵
/src
# ...

# --------
# バックエンド
# --------
# ...
/scripts
/secrets
  local.dev.quden.io-key.pem # プライベートキー
  local.dev.quden.io.pem # 公開鍵
/src
/test
# ...

HTTPS で起動する場合は以下のコマンドを実行します。

bash
# フロント
$ yarn dev:docker:up:https

# バックエンド
$ yarn dev:docker:up:https

https://local.dev.quden.io:3000/ にアクセスして、クリップ一覧・再生ができてたら、ひとまず環境構築は終了です！

ステージング環境 https://app.dev.quden.io にアクセスする ​

開発環境には Basic 認証がかけられています。以下の情報を参照してアクセスしてください。

plain
username: quden-admin
password: quden9uden

新たに yarn add でライブラリを追加した場合 ​

yarn dev:docker:build_up でイメージを再ビルドしてください！

Why： 開発環境は Dockerfile.local にイメージを定義して作っており、ライブラリはローカルの node_modules ではなく、コンテナ内にインストールされた node_modules を参照するようにしているためです。そのため、 yarn add しただけでは can't resolve 的なエラーがでます。

ちなみに、古い image が残って PC のストレージを食うので、

デプロイフロー ​

development ブランチがデフォルトブランチであり、 development から main または production ブランチにマージすることで各種デプロイが実行されます。

タイミングは下記を参照してください。

  • development branch に PR を Open したとき
    • yarn lint と yarn build が走ります
  • main branch に merge したとき
    • Vercel に対して deploy を指示する GitHub Actions が実行されます
    • staging 環境 (https://app.dev.quden.io) に対して、Vercel 上で build および deploy が実行されます
  • production branch に merge したとき
    • Vercel に対して deploy を指示する GitHub Actions が実行されます
    • production 環境 (https://app.quden.io) に対して、Vercel 上で build および deploy が実行されます

Tips ​

スタイリング ​

するときは classnames を使うと便利。

typescript
// Button.tsx
import React, { FC } from "react";
import cn from "classnames"; // これのこと

type Props = {
  color?: "primary";
  onClick?: () => void;
};

export const Button: FC<Props> = (props) => {
  const { children, color, onClick } = props;

  return (
    <button
      onClick={onClick}
      className={cn("rounded-md", "p-4", "text-white", {
        "bg-primary": color === "primary",
      })}
      type="button"
    >
      {children}
    </button>
  );
};

デバッグおよびオペレーショナルなロギング ​

は logdown ベースの logger を是非使ってください。

typescript
import { logger } from "../../path/to/logger";
import { AppError } from "../path/to/custom-error";

logger.log("hoge");
logger.error(new AppError("this is error"));

開発環境で使用できるメールアドレス ​

ユーザー登録などを開発環境で行う際にメールアドレスが必要になることがあります。 これには @quden.io や@toruca.comを使用できます。@より前はユニークであることが望ましいため日付や名前を入れるなどの工夫が必要です。 受信したメールは #notify_dev-email-quden で確認することができます。

json
メールアドレス例： test+yuki+20230501@quden.io

local検証で特殊な作業が必要なケース ​

amplitudeにeventを飛ばしたいとき ​

以下の２箇所に、 .env.developmentの ANALYTICS_WRITE_KEYの値を入れる

すると、amplitudeでイベントを確認することができる

以下、背景など

計測したいユーザーの行動は、amplitudeにイベントを飛ばしており、amplitudeのuser look-upで確認することができる

javascript
// イベント発火例
global.analytics.track(trackEvents.tag.created, {
  name: data.name,
} as TagCreated);

staging/prodどちらも同じamplitude環境を使っているので、localで検証する際も同じ環境に対して、イベントを発火するように (amplitude user のproperties で本番環境かどうか識別しているため、問題はない)

amplitude event explorerのchrome拡張を使うと、debugがしやすくなるかも amplitudeが有効になっていると、以下画像のようにイベントを確認できる

トラブルシューティング ​

変更を commit しても pre-commit の lint が走らない ​

husky の設定がうまくいっていない可能性があるので、yarn husky install を実行してみてください。

コンテナの起動時のエラー(M1 macOS) ​

yarn installの途中で止まってしまう場合、Dockerfile.localの先頭にある

docker
FROM node:lts-alpine

を

docker
FROM --platform=linux/amd64 node:lts-alpine

に書き換えてみてください。

ERR_SSL_PROTOCOL_ERRORとブラウザに出てHTTPS通信ができない ​

ローカルの認証局がない可能性があるのでmkcert -installを実行してみてください。

error Command failed with signal "SIGKILL".となりhttpsで起動していたのにhttpで再起動されてしまう ​

dockerのresourceが足りない可能性があります。メモリなどを上げてみてください。