npm package: @seveti/core
Description: Shared React components for Seveti projects
Author: seveti
Latest version: 1.6.4

# @seveti/core

Shared React components for Seveti projects.

## Installation

```bash
npm install @seveti/core
```

### TypeScript Configuration

This package includes proper TypeScript declaration files (`.d.ts`) with no external import dependencies. It works seamlessly with any TypeScript configuration.

**Recommended `tsconfig.json` settings:**

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler", // or "node16" / "nodenext" / "node"
    "skipLibCheck": true,          // Recommended to avoid dependency type conflicts
    "esModuleInterop": true,       // Recommended for better module interop
    "jsx": "react-jsx"             // or "preserve" for Next.js
  }
}
```

**What's included:**

- ✅ Fully typed components with autocomplete support
- ✅ No problematic external type imports (e.g., `class-variance-authority/types`)
- ✅ Works with all modern module resolution strategies
- ✅ React 19+ types included

**Note:** `skipLibCheck: true` is recommended to prevent transitive dependency type conflicts, but your IDE will still provide full autocomplete and type checking for your own code.

## Components

### DemoRenderer

A component for rendering interactive demos with code preview and fullscreen capabilities.

```tsx
import { DemoRenderer } from '@seveti/core';

function MyPage() {
  return (
    <DemoRenderer
      htmlContent={htmlString}
      codeContent={codeString}
      demoName="My Demo"
    />
  );
}
```

#### Props

- `htmlContent` (string): HTML content to render in the preview iframe
- `codeContent` (string): Source code to display in the code tab
- `demoName` (string): Name of the demo for the iframe title

## Development

```bash
# Build the package
npm run build

# Watch mode for development
npm run dev
```

## Publishing (Maintainers Only)

This package follows [Semantic Versioning (SemVer)](https://semver.org/):

- **MAJOR** version (X.0.0): Breaking changes that require code updates in consuming projects
- **MINOR** version (0.X.0): New features that are backward compatible
- **PATCH** version (0.0.X): Bug fixes that are backward compatible

### Setup Authentication

Before publishing, set up your npm authentication:

#### 1. Create `.env` file

```bash
cd packages/core
cp .env.example .env
```

#### 2. Add your granular access token

Edit `.env` and add your token:

```bash
NPM_TOKEN=npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Getting a granular access token:**

1. Go to [npm tokens page](https://www.npmjs.com/settings/YOUR_USERNAME/tokens)
2. Click "Generate New Token" → "Granular Access Token"
3. Set permissions: **Read and write** for `@seveti/core` package
4. Copy the token to your `.env` file

**Important:** Never commit `.env` to git (it's already in `.gitignore`)

### Quick Publish

Use the publish script to handle everything automatically:

```bash
# Patch version (bug fixes): 1.0.0 → 1.0.1
./publish.sh patch

# Minor version (new features): 1.0.0 → 1.1.0
./publish.sh minor

# Major version (breaking changes): 1.0.0 → 2.0.0
./publish.sh major
```

**You will be prompted for a 2FA code:**

```text
🔐 Two-Factor Authentication Required
  Open your authenticator app and enter the 6-digit code:
  OTP Code: ______
```

The script will:

1. ✅ Check for `.env` file and `NPM_TOKEN`
2. ✅ Build the package (`npm run build`)
3. ✅ Bump the version number
4. ✅ Prompt for 2FA code from your authenticator app
5. ✅ Publish to npm with `--access public` and `--otp` (required for scoped packages)
6. ✅ Create a git commit and tag
7. ✅ Push to remote with tags

**Note:** OTP codes are only valid for 30 seconds. If publishing fails, run the script again with a fresh code.

### Manual Publishing Steps

If you prefer to publish manually:

#### 1. Load environment variables and create .npmrc

```bash
cd packages/core

# Load .env file
source .env

# Export token so npm can use it
export NPM_TOKEN

# Create temporary .npmrc file for authentication
echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" > .npmrc
```

#### 2. Build the Package

```bash
npm run build
```

#### 3. Update Version

```bash
# Patch (bug fixes): 1.0.0 → 1.0.1
npm version patch --no-git-tag-version

# Minor (new features): 1.0.0 → 1.1.0
npm version minor --no-git-tag-version

# Major (breaking changes): 1.0.0 → 2.0.0
npm version major --no-git-tag-version
```

#### 4. Verify Package Contents

```bash
# Preview what will be published
npm pack --dry-run
```

#### 5. Publish to npm

```bash
# Get OTP code from your authenticator app (valid for 30 seconds)
# Then publish with the code:
npm publish --access public --otp=123456

# Replace 123456 with your actual 6-digit code
```

#### 6. Clean up .npmrc (security)

```bash
# Remove the temporary .npmrc file
rm -f .npmrc
```

#### 7. Commit and Tag

```bash
# Get the new version from package.json
NEW_VERSION=$(node -p "require('./package.json').version")

# Commit the version change
git add package.json
git commit -m "chore(core): release v$NEW_VERSION"

# Create a git tag
git tag -a "core-v$NEW_VERSION" -m "seveti-core v$NEW_VERSION"

# Push to remote with tags
git push --follow-tags
```

### Version Guidelines

**Patch (1.0.X)** - Use when:

- Fixing bugs
- Improving documentation
- Performance optimizations
- Internal refactoring (no API changes)

**Minor (1.X.0)** - Use when:

- Adding new components
- Adding new props (with defaults)
- Adding new optional features
- Deprecating features (but not removing)

**Major (X.0.0)** - Use when:

- Removing components
- Removing or renaming props
- Changing prop types
- Any breaking API changes
- Changing peer dependencies (major versions)

### Example Workflow

```bash
# 1. Make your changes to src/
# 2. Test locally in seveti-web
# 3. When ready to publish:

npm run release:minor  # For new features

# 4. Update consuming projects:
cd ../../vision-to-app-atx
npm install @seveti/core@latest
```

### Updating Consuming Projects

After publishing a new version:

#### seveti-web (uses workspace)

```bash
# Already using latest local version
npm run build
```

#### vision-to-app-atx (uses npm package)

```bash
npm install @seveti/core@latest
```

### Troubleshooting

#### "npm ERR! You need to be logged in" or "npm ERR! code E401"

```bash
# Make sure your .env file exists and has NPM_TOKEN set
cat .env

# Load the environment variable and create .npmrc
source .env
export NPM_TOKEN
echo "//registry.npmjs.org/:_authToken=\${NPM_TOKEN}" > .npmrc

# Verify .npmrc was created
cat .npmrc

# Try publishing again
npm publish --access public

# Clean up after
rm -f .npmrc
```

#### "npm ERR! 402 Payment Required"

```bash
# First publish requires --access public
npm publish --access public
```

#### "npm ERR! 403 Forbidden"

```bash
# Your token may not have the right permissions
# Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
# Generate a new token with "Read and write" permissions for @seveti/core
# Update your .env file with the new token
```

#### "npm ERR! EOTP - This operation requires a one-time password"

```bash
# You need to provide a 2FA code
# The publish script will prompt you for it
# Or manually add --otp flag:
npm publish --access public --otp=123456

# Make sure to use a fresh code (valid for 30 seconds)
```

#### "npm ERR! This command does not support workspaces"

```bash
# Make sure you're in the package directory, not the workspace root
cd packages/core

# Use the publish script which handles workspace issues
./publish.sh patch
```

#### Build fails before publish

```bash
# Fix TypeScript/build errors, then retry
npm run build
npm version patch --no-git-tag-version
npm publish --access public
```

## License

MIT