# はじめに
Source: https://www.yagisan.app/docs/
## yagisan-reportsとは
yagisan-reportsは、**WebブラウザとNode.jsで動作**するJavaScript製の帳票エンジンです。
- **HTML、JSX、XAML、Androidに影響を受けた宣言的なXML形式のテンプレート**で、Web開発者が読み書きしやすいように意識して設計しています。
- JIS第四水準漢字（JIS X 0213:2004）、異体字、縦書き、禁則処理、複雑な表組みなど、**日本語帳票に必要な機能をサポート**しています。
- **改ページ制御を自動で行う**ことができ、可変帳票も問題ありません。数百ページ規模の**大量ページ出力も高速に処理可能**です。
- **npmライブラリとして提供**されており、標準的なWeb開発のツールチェインに組み込むことができます。
- **Webブラウザ単体で帳票出力**が可能です。**帳票サーバーを排除して大幅なコスト削減**を図ったり、**フロント側の対応だけで帳票機能を追加**することができます。
## 料金
yagisan-reportsは有償製品ですが、**開発やテスト（CI/CD環境を含む）での使用は無償**です。
本番運用時のみ、有償契約が必要となります。
契約は**プロダクト単位（または組織単位：エンタープライズ版）**で行うため、**サーバー台数やユーザー数に応じた追加費用は一切発生しません**。
有償契約の詳細や無償使用（開発者ライセンス）については、次のページをご覧ください。
- [料金](/pricing)
- [利用規約](/terms)
## 今すぐ動かしてみる
yagisan-reportsは **5分以内** で実際に動作を確認できます。
インストールやユーザー登録などは一切不要です。
### ライブデモ
[https://demo.yagisan.app/](https://demo.yagisan.app/) では、実務で使われる帳票を想定したサンプルを多数公開しています。
### Webブラウザで動かしてみる
次のコードをコピーし、HTMLファイル（例えば `index.html`）として保存します。
このHTMLファイルをWebブラウザで開いてボタンをクリックすると、帳票PDFが出力されます。
```html
```
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs';
# 開発を始める
Source: https://www.yagisan.app/docs/devguide/start-developing
:::info
本手順は将来のバージョンで改訂される予定です。
:::
## テキストエディタの準備
yagisan-reportsの開発では、XMLを編集できるテキストエディタが必要です。
必須ではありませんが、XML Schema（XSD 1.0）に対応しているものを推奨します。
[Visual Studio Code](https://code.visualstudio.com/) をお使いの場合は、次の拡張をインストールすると推奨環境が整います。
- [XML Language Support by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml)
## Node.jsのインストール
[Node.js 公式サイト](https://nodejs.org/) からインストーラーをダウンロードしてインストールするか、`mise` や `nvm` などのバージョン管理ツールを使用して Node.js をインストールしてください。
使用可能なNode.jsのバージョンについては、[動作環境・サポートポリシー](../requirements-and-support.md) をご覧ください。
## npmパッケージのインストール
yagisan-reports開発ツール群をインストールします。
```sh
npm install @yagisan-reports/sdk
npm install -D https://github.com/DenkiYagi/yagisan-reports-devtool
```
エンタープライズ版を使用する場合は、次のコマンドを使用してください。
```sh
npm install @yagisan-reports/sdk-enterprise
npm install -D https://github.com/DenkiYagi/yagisan-reports-devtool
```
```sh
pnpm add @yagisan-reports/sdk
pnpm add -D https://github.com/DenkiYagi/yagisan-reports-devtool
```
エンタープライズ版を使用する場合は、次のコマンドを使用してください。
```sh
pnpm add @yagisan-reports/sdk-enterprise
pnpm add -D https://github.com/DenkiYagi/yagisan-reports-devtool
```
:::note
yagisan-reports-devtool は、将来的に npm レジストリで公開する予定です。
:::
## 帳票テンプレートの作成
以下のXMLをコピーして `layout.xml` として保存します。
文字エンコーディングはUTF-8を使用してください。
```xml
${message}
このPDFはyagisan-reportsによって作成されました
```
`yagisan` コマンドを使って、XMLファイルから帳票テンプレートファイルを作成します。
```sh
npx yagisan yrt pack layout.xml -O template.yrt
```
```sh
pnpm exec yagisan yrt pack layout.xml -O template.yrt
```
## アプリケーションへの組み込み
### Node.jsで実行する
前述の手順で作成した帳票テンプレートファイルをアクセス可能な場所に配置し、以下のようにコードを記述します。
```javascript
import { createEngine } from '@yagisan-reports/sdk';
// エンタープライズ版を使用する場合:
// import YagisanReports from '@yagisan-reports/sdk-enterprise';
import { readFile, writeFile } from 'fs/promises';
// 帳票テンプレートファイルの読み込み
const yrt = await readFile('path/to/template.yrt');
// 帳票エンジンのセットアップ
const engine = createEngine();
const template = await engine.loadTemplate(yrt);
const generator = await template.createPdfReportGenerator();
// 帳票を出力
const report = await generator.generate({
message: 'hello!\nyagisan-reports!!'
});
const pdf = await report.getContent();
writeFile('hello.pdf', Buffer.from(pdf));
// 帳票エンジンの破棄
generator.dispose();
template.dispose();
engine.dispose();
```
```javascript
const { createEngine } = require('@yagisan-reports/sdk');
// エンタープライズ版を使用する場合:
// const { createEngine } = require('@yagisan-reports/sdk-enterprise');
const { readFile, writeFile } = require('fs/promises');
(async () => {
// 帳票テンプレートファイルの読み込み
const yrt = await readFile('path/to/template.yrt');
// 帳票エンジンのセットアップ
const engine = createEngine();
const template = await engine.loadTemplate(yrt);
const generator = await template.createPdfReportGenerator();
// 帳票を出力
const report = await generator.generate({
message: 'hello!\nyagisan-reports!!'
});
const pdf = await report.getContent();
writeFile('hello.pdf', Buffer.from(pdf));
// 帳票エンジンの破棄
generator.dispose();
template.dispose();
engine.dispose();
})();
```
:::info
Node.jsで実行する場合、bundler を使用して yagisan-reports をバンドルすることはできません。
:::
### Webブラウザで実行する
Webブラウザ上で帳票出力を行う場合、3つのセットアップ方法があります。
- パブリックCDNを使う
- jsDelivr などのパブリックCDNにホストされた yagisan-reports を使用します。
- もっとも手軽な方法ですが、パブリックCDNの利用規約・プライバシーポリシー等に従う必要があります。
- UMD版をセルフホストする
- yagisan-reports モジュールの配置を自分で管理すること以外は、「パブリックCDNを使う」方法とほぼ同等です。
- 任意のbundlerを使う
- Vite、webpack、esbuild などの任意の bundler を使用して yagisan-reports を組み込みます。
#### パブリックCDNを使う または UMD版をセルフホストする
あらかじめ、以下のファイルをHTTPアクセス可能な場所に配置してください。
- 前述の手順で作成した帳票テンプレートファイル
- **[セルフホストの場合のみ]** yagisan-reports の npm パッケージ（通常は `node_modules/@yagisan-reports/sdk`）に含まれるリソース群
- `umd.js`
- `reportworker.js`
- フォントファイル群（`*.ttf`, `*.glyphdata`, `*.txt`）
- フォントファイル群は全て同一のディレクトリに配置する必要があるため、npmパッケージを丸ごとコピーして配置することを推奨します。
HTMLファイルを作成します。以下の部分は環境に合わせて変更してください。
- `