From 0ae79f0d4c722814427e129fb73e3009a1bd6491 Mon Sep 17 00:00:00 2001 From: Hiroshi Nishito Date: Mon, 20 Jan 2025 20:59:32 +0900 Subject: [PATCH 1/3] =?UTF-8?q?init]README=E3=81=AE=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.ja.md | 144 ++++++++++++++++++++++++++++++++++++++++++ README.md | 138 +++++++++++++++++++++++++++++++++++++++- frontend/package.json | 1 + 3 files changed, 282 insertions(+), 1 deletion(-) create mode 100644 README.ja.md diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..9de4d36 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,144 @@ +## 目次 + +1. [README（日本語版）](#readme日本語版) +2. [README (English Version)](#readme-english-version) +3. [ファイル保存例](#ファイル保存例) + +--- + +## README（日本語版） + +以下は `README.ja.md` などのファイル名で配置することを想定した例です。 + +```md +# mdstream (日本語版) + +mdstream は、React (Vite) + TypeScript を使用したフロントエンドと、Serverless Framework (Node.js) を使用したバックエンドで構成されたサンプルプロジェクトです。MarkdownファイルをS3に保存し、それをWebアプリケーションで一覧・詳細表示する仕組みになっています。 + +## プロジェクト概要 + +- **フロントエンド**: + - `frontend/` ディレクトリ配下にあります。Vite をベースとしたReactアプリケーションです。 + - Markdownの読み込みやリスト表示、詳細表示の機能が含まれます。 + - `terms.md`, `privacy.md` といったMarkdownファイルを `/public/markdown/` に配置しており、`TermsPage` および `PrivacyPage` コンポーネントで表示しています。 + +- **バックエンド**: + - `backend/` ディレクトリ配下にあります。Serverless Framework を使用し、AWS Lambda 上で動作します。 + - S3 から Markdownファイルを取得し、API (HTTP) 経由でフロントエンドへ返すサンプルとなっています。 + +- **ライセンス**: + - 本プロジェクトは GNU General Public License (GPL) v3 で公開されています。詳細はリポジトリ直下の `LICENSE` をご覧ください。 + +--- + +## ディレクトリ構成 + +```bash +mdstream/ + ├─ frontend/ # React + Vite プロジェクト + │ ├─ public/markdown # Markdownファイル + │ ├─ src/ # ソースコード (コンポーネントなど) + │ ├─ package.json + │ ├─ vite.config.ts + │ └─ ...(その他コンフィグ) + ├─ backend/ # Serverless Framework (Node.js) プロジェクト + │ ├─ src/ + │ ├─ serverless.yml + │ └─ package.json + ├─ LICENSE + └─ README.md (あるいは README.ja.md) +``` + +--- + +## セットアップ・利用方法 + +### 1. リポジトリのクローン + +```bash +git clone https://github.com/yourname/mdstream.git +cd mdstream +``` + +### 2. フロントエンドのセットアップ + +```bash +cd frontend +npm install +``` + +- 開発サーバ起動 (ローカルAPI用) + ```bash + npm run dev:local + ``` + - デフォルトでは [http://localhost:5173](http://localhost:5173) が開きます。 + - `.env.dev`（または同等の環境変数設定ファイル）が存在する場合は、それを読み込みます。 +- ビルド + ```bash + npm run build:dev + # or + npm run build:prod + ``` + - ビルド成果物は `frontend/dist/` に出力されます。 + +### 3. バックエンドのセットアップ + +```bash +cd ../backend +npm install +``` + +- ローカル開発 (serverless-offline使用) + ```bash + npm run dev:local + ``` + - `.env.local` や `.env.dev` などのファイルに `BUCKET_NAME` や `ALLOWED_REFERER` を設定し、S3バケットとの連携を模擬します。 + - Serverless Offline により、[http://localhost:3000](http://localhost:3000) などで API をテストできます。（`serverless.yml` の設定により変わります） + +- デプロイ例 (開発環境) + ```bash + npm run deploy:dev + ``` + - AWS Lambda にデプロイされます。実際に利用するにはAWSアカウントの設定・認証が必要です。 + +--- + +## Markdownファイルの追加・編集 + +- フロントエンドの `/public/markdown/` ディレクトリ内に、`.md` ファイルを追加すると、`PrivacyPage.tsx` や `TermsPage.tsx` で直接参照できます。 +- バックエンド側で Markdown を管理する場合は、AWS S3 にファイルをアップロードし、`serverless.yml` や環境変数 (`S3_PREFIX` など) を通して連携します。 + - その場合、`fetchMarkdownList` / `fetchMarkdownDetail` 関数が参照する API が S3 から直接読み込みます。 + +--- + +## カスタマイズ方法 + +1. **デザイン・スタイルの修正** + - `frontend/src/styles/` 配下の `.scss` や `.css` を編集してUIを変更できます。 +2. **コンポーネントの追加** + - `frontend/src/components/` に新規コンポーネントを追加し、必要に応じてルーティング (`App.tsx`) を編集します。 +3. **API エンドポイントの変更** + - `backend/src/handler.ts` 内でロジックを追加・修正します。 + - `serverless.yml` でAPIパスやAWSの設定を変更できます。 +4. **ライブラリの追加** + - フロントエンドの場合 `frontend/package.json`、バックエンドの場合 `backend/package.json` に依存を追加し、必要に応じて `npm install` を実行してください。 + +--- + +## 貢献方法 (Contributing) + +- バグ報告や機能要望はIssueを立ててください。 +- プルリクエストを歓迎します。大きな変更の場合は事前にIssueで議論しましょう。 + +--- + +## ライセンス + +- このプロジェクトは GNU GPL v3 ライセンスの下で公開されています。 +- 詳細は [LICENSE](./LICENSE) ファイルをご確認ください。 + +--- + +## 問い合わせ + +- 質問や不具合に関しては、Issueまたは [info@itc.tokyo](mailto:info@itc.tokyo) までご連絡ください。 \ No newline at end of file diff --git a/README.md b/README.md index 56c423b..d90b24a 100644 --- a/README.md +++ b/README.md @@ -1 +1,137 @@ -# mdstream +# mdstream (English) + +mdstream is a sample project consisting of a **React (Vite) + TypeScript** frontend and a **Serverless Framework (Node.js)** backend. It uses AWS S3 to store Markdown files and fetches them via HTTP APIs for listing and detail views in the web application. + +## Overview + +- **Frontend**: + - Located under the `frontend/` directory, built with Vite + React + TypeScript. + - Displays a list of Markdown files and their contents. + - Also demonstrates how to load local markdown (e.g., `terms.md` and `privacy.md`) in the `/public/markdown/` folder and render it with React. + +- **Backend**: + - Located under the `backend/` directory, built with the Serverless Framework on Node.js. + - Fetches Markdown files from an S3 bucket and serves them via an HTTP API. + - The environment variables (`BUCKET_NAME`, `ALLOWED_REFERER`, etc.) control where the Markdown files are stored and which referers are allowed. + +- **License**: + - This project is published under **GNU General Public License (GPL) v3**. + - See the `LICENSE` file for more details. + +--- + +## Directory Structure + +```bash +mdstream/ + ├─ frontend/ # React + Vite project + │ ├─ public/markdown # Markdown files + │ ├─ src/ # Source code (components, services, etc.) + │ ├─ package.json + │ ├─ vite.config.ts + │ └─ ...other configs + ├─ backend/ # Serverless Framework (Node.js) project + │ ├─ src/ + │ ├─ serverless.yml + │ └─ package.json + ├─ LICENSE + └─ README.md (or README.ja.md for Japanese) +``` + +--- + +## Getting Started + +### 1. Clone the Repository + +```bash +git clone https://github.com/yourname/mdstream.git +cd mdstream +``` + +### 2. Frontend Setup + +```bash +cd frontend +npm install +``` + +- **Local Development** (connecting to a local API): + ```bash + npm run dev:local + ``` + - By default, the local dev server runs at [http://localhost:5173](http://localhost:5173). + - It will load environment variables from `.env.dev` (or any `.env.*` specified). +- **Build** + ```bash + npm run build:dev + # or + npm run build:prod + ``` + - The build output goes to `frontend/dist/`. + +### 3. Backend Setup + +```bash +cd ../backend +npm install +``` + +- **Local Development (serverless-offline)**: + ```bash + npm run dev:local + ``` + - This will read environment variables such as `BUCKET_NAME` and `ALLOWED_REFERER` from `.env.dev` or similar. + - The local serverless-offline endpoint (e.g., http://localhost:3000) will serve the API (depending on your `serverless.yml` config). +- **Deploy to AWS Example**: + ```bash + npm run deploy:dev + ``` + - Requires your AWS credentials to be configured. + - Deploys the backend as AWS Lambda functions. + +--- + +## Editing / Adding Markdown Files + +- **Local** (frontend-based): + - Simply place new `.md` files under `frontend/public/markdown/`. + - Import or fetch them in your React components (like `PrivacyPage.tsx` or `TermsPage.tsx`). +- **Backend (S3-based)**: + - Upload your `.md` files to the appropriate S3 bucket. + - Update environment variables (`S3_PREFIX`, etc.) to point to the correct location. + - The `fetchMarkdownList` and `fetchMarkdownDetail` functions in `frontend/src/services/api.ts` call the API endpoints that read from S3. + +--- + +## Customization + +1. **Styling**: + - Edit SCSS/CSS files in `frontend/src/styles/` to change the UI appearance. +2. **Add Components**: + - Create new React components in `frontend/src/components/`, and add corresponding routes in `App.tsx` as needed. +3. **API Changes**: + - Modify logic in `backend/src/handler.ts` or the `serverless.yml` file to adjust endpoints, environment variables, AWS settings, etc. +4. **Dependencies**: + - Update `frontend/package.json` or `backend/package.json` for any additional libraries. + - Run `npm install` to install new dependencies. + +--- + +## Contributing + +- Please open an Issue for bugs or feature requests. +- Pull requests are welcome. For major changes, consider discussing them in an Issue first. + +--- + +## License + +- Released under the **GNU GPL v3** license. +- Refer to [LICENSE](./LICENSE) for details. + +--- + +## Contact + +- For questions or issues, please open an Issue or email [info@itc.tokyo](mailto:info@itc.tokyo). \ No newline at end of file diff --git a/frontend/package.json b/frontend/package.json index 6646fb5..d76900c 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -6,6 +6,7 @@ "scripts": { "dev:local": "cross-env VITE_API_BASE_URL=http://localhost:3000 vite", "dev:remote": "env-cmd -f .env.dev vite", + "dev:prod": "env-cmd -f .env.prod vite", "build:dev": "tsc -b && vite build --mode dev", "build:prod": "tsc -b && vite build --mode prod", "lint": "eslint .", From d8868653139b65c4ea88b0a216368cf527485c72 Mon Sep 17 00:00:00 2001 From: Hiroshi Nishito Date: Mon, 20 Jan 2025 21:09:56 +0900 Subject: [PATCH 2/3] =?UTF-8?q?init]=E8=A8=80=E8=AA=9E=E3=83=AA=E3=83=B3?= =?UTF-8?q?=E3=82=AF=E3=81=AE=E4=BF=AE=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.ja.md | 9 ++------- README.md | 3 +++ 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/README.ja.md b/README.ja.md index 9de4d36..7ae2ffe 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,10 +1,5 @@ -## 目次 - -1. [README（日本語版）](#readme日本語版) -2. [README (English Version)](#readme-english-version) -3. [ファイル保存例](#ファイル保存例) - ---- +## リンク +- [README (English Version)](./README.md) ## README（日本語版） diff --git a/README.md b/README.md index d90b24a..15776d1 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # mdstream (English) +## Link +[日本語版はこちら](./README.ja.md) + mdstream is a sample project consisting of a **React (Vite) + TypeScript** frontend and a **Serverless Framework (Node.js)** backend. It uses AWS S3 to store Markdown files and fetches them via HTTP APIs for listing and detail views in the web application. ## Overview From 57bf5ea611fff1df265004a8d7cd9dcfda3045a0 Mon Sep 17 00:00:00 2001 From: Hiroshi Nishito Date: Mon, 20 Jan 2025 21:11:12 +0900 Subject: [PATCH 3/3] =?UTF-8?q?init]README=E3=81=AE=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=E3=80=81English?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.ja.md | 11 +++-------- README.md | 5 +++-- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/README.ja.md b/README.ja.md index 7ae2ffe..82fce24 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,15 +1,10 @@ -## リンク -- [README (English Version)](./README.md) - -## README（日本語版） - -以下は `README.ja.md` などのファイル名で配置することを想定した例です。 - -```md # mdstream (日本語版) mdstream は、React (Vite) + TypeScript を使用したフロントエンドと、Serverless Framework (Node.js) を使用したバックエンドで構成されたサンプルプロジェクトです。MarkdownファイルをS3に保存し、それをWebアプリケーションで一覧・詳細表示する仕組みになっています。 +## リンク +- [README (English Version)](./README.md) + ## プロジェクト概要 - **フロントエンド**: diff --git a/README.md b/README.md index 15776d1..c4164cc 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ # mdstream (English) +mdstream is a sample project consisting of a **React (Vite) + TypeScript** frontend and a **Serverless Framework (Node.js)** backend. It uses AWS S3 to store Markdown files and fetches them via HTTP APIs for listing and detail views in the web application. + + ## Link [日本語版はこちら](./README.ja.md) -mdstream is a sample project consisting of a **React (Vite) + TypeScript** frontend and a **Serverless Framework (Node.js)** backend. It uses AWS S3 to store Markdown files and fetches them via HTTP APIs for listing and detail views in the web application. - ## Overview - **Frontend**: