Welcome to the Bluefly.io code repository. By logging in, you agree to comply with our terms of service and code of conduct.

Skip to content

Create @bluefly/technical-guide NPM Package

Objective

Structure technical-guide as a publishable npm package that other projects can import for design tokens, validators, and API registry metadata.

Package Structure

Directory Layout

``` technical-guide/ ├── src/ │ ├── tokens/ # Design tokens (JSON/YAML) │ │ ├── colors.json │ │ ├── typography.json │ │ ├── spacing.json │ │ ├── motion.json │ │ └── index.ts │ ├── schemas/ # Shared OpenAPI components │ │ ├── common.schema.yml │ │ ├── errors.schema.yml │ │ └── index.ts │ ├── validation/ # Validators and linters │ │ ├── brand-validator.ts │ │ ├── api-linter.ts │ │ └── index.ts │ └── registry/ # API registry index │ ├── registry.yaml │ ├── platform-index.yaml │ └── index.ts ├── dist/ # Compiled output ├── package.json ├── tsconfig.json └── README.md ```

Package.json Configuration

```json { "name": "@bluefly/technical-guide", "version": "1.0.0", "description": "Standards library for LLM Platform: design tokens, API registry, validators", "main": "dist/index.js", "types": "dist/index.d.ts", "exports": { "./tokens": { "import": "./dist/tokens/index.js", "types": "./dist/tokens/index.d.ts" }, "./schemas": { "import": "./dist/schemas/index.js", "types": "./dist/schemas/index.d.ts" }, "./validation": { "import": "./dist/validation/index.js", "types": "./dist/validation/index.d.ts" }, "./registry": { "import": "./dist/registry/index.js", "types": "./dist/registry/index.d.ts" } }, "bin": { "technical-guide": "./dist/cli/index.js" } } ```

CLI Commands

  • `technical-guide validate-brand ` - Validate brand compliance
  • `technical-guide validate-api ` - Validate OpenAPI spec
  • `technical-guide check-standards ` - Check project standards
  • `technical-guide export-tokens ` - Export tokens (CSS, SCSS, etc.)

Build Configuration

  • TypeScript compilation
  • Include JSON/YAML files in output
  • Generate type definitions
  • Bundle validators
  • Tree-shakeable exports

Publishing

  • Publish to GitLab npm registry
  • Semantic versioning
  • Automated releases via CI/CD
  • Changelog generation

Documentation

  • README with usage examples
  • API documentation
  • Migration guide
  • Link to GitLab Wiki for detailed docs

Usage Examples

```typescript // Import design tokens import { colors, typography } from '@bluefly/technical-guide/tokens'; const primaryColor = colors.primary[600];

// Import validators import { validateBrand } from '@bluefly/technical-guide/validation'; const result = validateBrand(myDesign);

// Import API registry import { getAPIRegistry } from '@bluefly/technical-guide/registry'; const apis = await getAPIRegistry(); ```

Tasks

  • Create package.json with proper exports
  • Set up TypeScript build
  • Create CLI entry point
  • Add build scripts
  • Configure GitLab npm registry publishing
  • Add pre-publish validation
  • Create comprehensive README
  • Add usage examples

Related

  • Epic: #1
  • Previous: #7 (extract design tokens)
  • Next: #9 (update agent-router)
  • Depends on: #5 (registry), #7 (tokens)

Success Criteria

  • ✅ Package builds successfully
  • ✅ All exports are typed
  • ✅ CLI commands work
  • ✅ Published to GitLab npm registry
  • ✅ Other projects can install and import
  • ✅ Tree-shakeable (import only what you need)