kintone-plugin-docx/AGENTS.md

AGENTS.md - Development Guidelines for Kintone Word Output Plugin

This document provides guidelines and useful information for AI agents and developers working on the Kintone Word Output Plugin project. It includes setup instructions, coding standards, and best practices to ensure efficient and consistent development.

Project Overview

• Name: Kintone Word Output Plugin
• Purpose: A Kintone plugin that formats and downloads data using Word (.docx) templates.
• Tech Stack:
  • Frontend: React (TypeScript)
  • Build Tool: rspack
  • Linting/Formatting: Biome
  • Template Engine: docxtemplater with angular-expressions
  • Kintone Integration: @kintone/rest-api-client
• Languages: TypeScript, JavaScript
• Package Manager: npm

Development Environment Setup

Prerequisites

• Node.js 18+
• npm (comes with Node.js)

Initial Setup

1. Clone the repository
2. Run npm install to install dependencies
3. Run npm run gen:key to generate a private key for development
4. Run npm start to start the development server

Useful Scripts

• npm run build: Development build
• npm run build:prod: Production build
• npm run develop: Watch mode build
• npm run lint: Run Biome linter
• npm run format: Format code with Biome
• npm run cspell: Check spelling
• npm run upload: Upload plugin to Kintone (requires env setup)

Coding Standards

TypeScript

• Use strict TypeScript settings (see tsconfig.json)
• Prefer interfaces over types for object definitions
• Use proper typing for Kintone API responses
• Avoid any type; use specific types or unknown

React Components

• Use functional components with hooks
• Follow React best practices for state management
• Use TypeScript for prop types
• Implement error boundaries where appropriate

File Structure

• src/common/: Shared utilities and components
• src/config/: Configuration UI components
• src/desktop/: Desktop app components and logic
• src/types/: TypeScript type definitions
• plugin/: Kintone plugin manifest and assets
• scripts/: Build and utility scripts

Naming Conventions

• Use camelCase for variables and functions
• Use PascalCase for components and classes
• Use kebab-case for file names
• Prefix custom hooks with use

Code Quality Tools

Biome

• Used for linting and formatting
• Configuration in biome.json
• Run npm run lint to check code
• Run npm run format to auto-fix issues

TypeScript Compiler

• Strict mode enabled
• Check for errors with npm run build

Spell Checker

• Uses cspell for spell checking
• Configuration in cspell config files
• Run npm run cspell to check

Testing

Current Testing Setup

• No automated tests are currently implemented
• Manual testing required for:
  • Plugin installation in Kintone
  • Template rendering with various data types
  • Error handling scenarios

Recommended Testing Approach

• Add unit tests for utility functions (e.g., data formatting)
• Add integration tests for template generation
• Test with different Kintone field types
• Test error scenarios (invalid templates, missing data)

Build and Deployment

Build Process

1. Pre-build: Generate keys and validate
2. Build with rspack (dev or prod mode)
3. Output: dist/plugin.zip for Kintone upload

Deployment

• Use npm run upload for development
• Manual upload via Kintone Plugin Uploader for production
• Requires proper environment variables for authentication

Kintone-Specific Considerations

Plugin Architecture

• Separate config and desktop JS files
• Config handles settings UI
• Desktop handles record view functionality
• Uses Kintone's plugin API

Data Handling

• Fields are mapped from Kintone records to template data
• Supports all Kintone field types
• Custom formatting for numbers, dates, calculations
• Handles subtable data as arrays

Template Engine

• Uses docxtemplater for .docx processing
• Custom filters available (see generateWordFileData.ts)
• Supports loops, conditionals, and expressions

Common Development Tasks

Adding a New Filter

1. Add filter function in generateWordFileData.ts
2. Update filters object in expressionParser.configure()
3. Document in README.md
4. Test with sample templates

Adding a New Field Type Support

1. Update record2templateData function
2. Handle formatting in appropriate helper functions
3. Add type checks and error handling
4. Test with sample data

Updating UI Components

1. Use existing UI components from src/common/ui/
2. Follow i18n pattern for text
3. Test in both config and desktop contexts

Troubleshooting

Common Issues

• Build fails: Check Node.js version, run npm install
• Plugin not loading: Verify manifest.json, check browser console
• Template errors: Validate .docx file, check field codes
• Upload fails: Check environment variables, Kintone permissions

Debug Tips

• Use browser dev tools for client-side debugging
• Check Kintone app logs for server-side issues
• Validate templates with docxtemplater documentation
• Test with minimal data sets first

Contributing

Pull Request Process

1. Create a feature branch
2. Make changes following coding standards
3. Run linting and build checks
4. Test manually in Kintone environment
5. Submit PR with clear description

Code Review Checklist

• Code follows TypeScript and React best practices
• No linting errors
• Proper error handling
• Tested with various data scenarios
• Documentation updated if needed

Resources

• Kintone Developer Documentation
• docxtemplater Documentation
• Biome Documentation
• React Documentation

AI Agent Guidelines

When working on this project:

• Always check existing code patterns before implementing new features
• Use the provided UI components and utilities
• Follow the established file structure
• Test changes in a Kintone environment
• Update documentation for any user-facing changes
• Prefer TypeScript over JavaScript for new code
• Use Biome for code quality checks
• Always use English for comments embedded in the code
• Respond to chat messages in the language used in the input