# newcore-widget-template

**Repository Path**: newcore2014/newcore-widget-template

## Basic Information

- **Project Name**: newcore-widget-template
- **Description**: 新核云 自定义widget 项目模板
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-02
- **Last Updated**: 2025-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Newcore Widget Template

A React + TypeScript template for building widgets that integrate with the Newcore open platform.

## Features

- 🚀 Modern React 19 with TypeScript support
- 📱 Multi-location widget support (TopBar, NavBar, SideBar, Background)
- 🎨 HeroUI component library integration
- 🌍 Internationalization (i18n) with react-i18next
- ⚡ Vite for fast development and optimized builds
- 🎯 Location-aware widget rendering
- 🔄 Hot module replacement (HMR) for development
- 📦 Tailwind CSS for styling
- 🛡️ TypeScript for type safety
- 🧪 Vitest for testing

## Installation

```bash
# Clone the project
git clone <repository-url>
cd widget_template

# Install dependencies
pnpm install
```

## Quick Start

### Development

Start the development server with hot reload:

```bash
# Start Vite dev server
pnpm run dev

# Start Newcore widget local server
pnpm run start
```

The development server runs on `http://localhost:3000` with HMR enabled for real-time code changes.

### Production Build

```bash
# Build for production
pnpm run build

# Preview production build
pnpm run start:prod

# Build for development
pnpm run build:dev
```

## Widget Locations

The template supports multiple widget locations within the Newcore platform:

### TopBar Widget
For widgets displayed in the top navigation bar.

### NavBar Widget
For widgets placed in the navigation sidebar.

### SideBar Widget
For widgets in the main sidebar area with configurable size:

```json
{
  "location": {
    "sideBar": {
      "paths": ["/butler/inbox"],
      "size": {
        "width": "100%",
        "height": "600px"
      }
    }
  }
}
```

### Background Widget
For background services and processes without UI.

## API Reference

### Widget Configuration

Configure your widget in `src/manifest.json`:

```json
{
  "name": "newcore-widget-app",
  "author": {
    "name": "Newcore"
  },
  "defaultLocale": "zh-CN",
  "private": true,
  "location": {
    "sideBar": {
      "paths": ["/butler/inbox"],
      "size": {
        "width": "100%",
        "height": "600px"
      }
    }
  },
  "version": "1.0",
  "frameworkVersion": "2.0"
}
```
`mainfest.json` config:
```
{
  "location": {
    "topBar": {},
    "navBar": {},
    "appBar": {},
    "sideBar": {
      "paths": ["/butler/inbox"],
      "size": {
        "width": "100%",
        "height": "600px"
      }
    },
    "background": {
      "paths": ["/butler/inbox"]
    }
  }
}
```
1. topBar: show on the header;
2. navBar: show on the navigation;
3. appBar: show in the mobile app;
4. sideBar: show on the right side;
5. background: run in the background;

### Location Context

Access the current widget location in your components:

```tsx
import { useLocation } from "./contexts/LocationContext";

function MyComponent() {
  const location = useLocation();

  return <div>Current location: {location}</div>;
}
```

### Internationalization

Use the i18n hook for translations:

```tsx
import { useI18n } from "./hooks/useI18n";

function MyComponent() {
  const { t } = useI18n();

  return <div>{t('welcome.message')}</div>;
}
```

### HTTP Requests

Use the configured axios instance:

```tsx
import request from "./utils/request";

// GET request
const data = await request.get('/users');

// POST request
const result = await request.post('/users', { name: 'John' });
```

## Project Structure

```
src/
├── app/                    # Main application components
│   ├── contexts/          # React contexts (LocationContext)
│   ├── hooks/             # Custom hooks (useI18n)
│   ├── locations/         # Location-specific components
│   │   ├── TopBarPlugin.tsx
│   │   ├── NavBarPlugin.tsx
│   │   ├── SideBarPlugin.tsx
│   │   └── BackgroundPlugin.tsx
│   ├── App.tsx            # Main app component with location routing
│   ├── hero.ts            # Hero configuration
│   ├── index.css          # Global styles
│   └── index.tsx          # App entry point
├── assets/                # Static assets
├── translations/          # i18n translation files
│   ├── en-US.json         # English translations
│   └── zh-CN.json         # Chinese translations
├── utils/                 # Utility functions
│   └── request.ts         # Axios HTTP client configuration
├── i18n.ts               # i18next configuration
├── index.html            # HTML template
├── manifest.json         # Widget configuration
└── vite-env.d.ts         # Vite type definitions
```

### Key Files

| File | Description |
|------|-------------|
| `src/app/App.tsx` | Main component with location-based routing |
| `src/manifest.json` | Widget configuration and metadata |
| `src/i18n.ts` | Internationalization setup |
| `src/utils/request.ts` | HTTP client with axios |
| `vite.config.ts` | Vite build configuration |
| `package.json` | Dependencies and scripts |

## Development

### Prerequisites

- Node.js >= 18.12.1
- pnpm (recommended package manager)

### Scripts

```bash
# Development with hot reload
pnpm run dev

# Start Newcore widget server (development)
pnpm run start

# Start Newcore widget server (production)
pnpm run start:prod

# Build for production
pnpm run build

# Build for development
pnpm run build:dev

# Watch mode (development build)
pnpm run watch

# Run tests
pnpm run test

# Lint code
pnpm run lint
```

### Testing

The project uses [Vitest](https://vitest.dev/) for testing. Test files are located in the `spec` directory.

```bash
pnpm run test
```

## Dependencies

### Core Dependencies

- **React 19** - Modern React with concurrent features
- **TypeScript** - Type safety and better developer experience
- **@heroui/react** - UI component library
- **Vite** - Fast build tool and development server
- **Tailwind CSS** - Utility-first CSS framework
- **i18next** - Internationalization framework
- **axios** - HTTP client for API requests
- **zustand** - State management
- **framer-motion** - Animation library

### Development Tools

- **ESLint** - Code linting
- **Prettier** - Code formatting
- **Vitest** - Testing framework
- **TypeScript ESLint** - TypeScript linting rules

## Browser Support

Modern browsers with ES2022+ support and postMessage API.

## Contributing

## License

*Use of this software is subject to important terms and conditions as set forth in the License file*

Copyright © 2024 Newcore

Licensed under the Apache License, Version 2.0. You may obtain a copy of the License at:
http://www.apache.org/licenses/LICENSE-2.0