#Versioning

import { VersionFeature } from '../components/VersionFeature';

# API Reference

<VersionFeature minVersion="v3">

## New Async API

v3 introduces a new Promise-based API:

`````javascript

// Available in v3+
const result = await api.fetchData();
```
</VersionFeature>

<VersionFeature maxVersion="v2">

## Legacy Callback API

v2 and earlier use callbacks:

```javascript

// v2 and earlier
api.fetchData((error, result) => {
  if (error) {
    console.error(error);
  }
});
```
</VersionFeature>
```

Implement VersionFeature component:

```tsx
// components/VersionFeature.tsx
import React from 'react';
import { useLocation } from 'rspress/runtime';

interface VersionFeatureProps {
  minVersion?: string;
  maxVersion?: string;
  children: React.ReactNode;
}

export function VersionFeature({
  minVersion,
  maxVersion,
  children,
}: VersionFeatureProps) {
  const location = useLocation();
  const currentVersion = location.pathname.split('/')[1];

  // Simple version comparison
  const versionNumber = (v: string) => parseInt(v.replace('v', ''), 10);
  const current = versionNumber(currentVersion);

  if (minVersion && current < versionNumber(minVersion)) {
    return null;
  }

  if (maxVersion && current > versionNumber(maxVersion)) {
    return null;
  }

  return <>{children}</>;
}
```

## Version Redirects

### Auto-Redirect

Redirect root path to latest version:

```typescript
export default defineConfig({
  builderConfig: {
    html: {
      redirects: [
        {
          from: '/',
          to: '/v4/',
        },
        {
          from: '/guide',
          to: '/v4/guide/',
        },
      ],
    },
  },
});
```

### Smart Version Detection

Redirect based on user context:

```tsx
// components/VersionRedirect.tsx
import { useEffect } from 'react';
import { useLocation } from 'rspress/runtime';

export function VersionRedirect() {
  const location = useLocation();

  useEffect(() => {
    // Check if accessing an archived version
    const currentVersion = location.pathname.split('/')[1];
    const savedVersion = localStorage.getItem('preferredVersion');

    // Redirect if user has a preferred version
    if (savedVersion && savedVersion !== currentVersion) {
      const newPath = location.pathname.replace(
        `/${currentVersion}`,
        `/${savedVersion}`
      );
      window.location.href = newPath;
    }
  }, [location]);

  return null;
}
```

## Version Search

### Per-Version Search

Configure version-specific search:

```typescript
export default defineConfig({
  themeConfig: {
    search: {
      versioned: true,
      // Create separate search index for each version
      indexes: [
        { version: 'v4', path: '/v4' },
        { version: 'v3', path: '/v3' },
        { version: 'v2', path: '/v2' },
      ],
    },
  },
});
```

## Best Practices

### Version Naming

1. **Semantic Versioning**: Use v1.x, v2.x, v3.x
2. **Clear Labels**: "v3.x (Latest)", "v2.x (LTS)", "v1.x (Archived)"
3. **Consistency**: Use same naming across all docs

### Content Management

1. **Keep in Sync**: Regularly update all supported versions
2. **Clear Migration Guides**: Provide migration paths between versions
3. **Highlight Changes**: Mark new features in each version
4. **Archive Old Versions**: Clearly mark EOL versions

### User Experience

1. **Default to Latest**: New users should see latest docs
2. **Preserve User Choice**: Remember user's selected version
3. **Clear Visual Cues**: Show current version prominently
4. **Easy Switching**: Make version switching effortless

## Automation

### Version Release Script

```bash
#!/bin/bash
# scripts/release-version.sh

NEW_VERSION=$1
CURRENT_VERSION=$(jq -r '.latest' versions.json)

if [ -z "$NEW_VERSION" ]; then
  echo "Usage: ./release-version.sh v4"
  exit 1
fi

echo "Creating new version: $NEW_VERSION"

# Copy current version
cp -r "docs/$CURRENT_VERSION" "docs/$NEW_VERSION"

# Update versions.json
jq ".latest = \"$NEW_VERSION\"" versions.json > versions.tmp.json
jq ".versions |= [{
  version: \"$NEW_VERSION\",
  label: \"$NEW_VERSION.x (Latest)\",
  path: \"/$NEW_VERSION\"
}] + ." versions.tmp.json > versions.json

rm versions.tmp.json

echo "✅ Version $NEW_VERSION created"
echo "Now update content in docs/$NEW_VERSION"
```

### Version Archive Script

```bash
#!/bin/bash
# scripts/archive-version.sh

VERSION=$1

if [ -z "$VERSION" ]; then
  echo "Usage: ./archive-version.sh v2"
  exit 1
fi

echo "Archiving version: $VERSION"

# Update version label
jq "(.versions[] | select(.version == \"$VERSION\") | .label) |= . + \" (Archived)\"" \
  versions.json > versions.tmp.json

mv versions.tmp.json versions.json

echo "✅ Version $VERSION archived"
```

## Troubleshooting

### Broken Version Links

**Issue**: Links point to wrong version

**Solution**:
```markdown
<!-- ✅ Use absolute paths -->
[API Reference](/v3/api/reference)

<!-- ❌ Avoid relative paths across versions -->
[API Reference](../../v2/api/reference)
```

### Version Selector Not Showing

**Issue**: Version selector doesn't appear

**Check**:
1. `versions.json` is properly formatted
2. Versioning enabled in config
3. At least 2 versions configured

### Search Shows All Versions

**Issue**: Search results mix all versions

**Solution**:
```typescript
export default defineConfig({
  themeConfig: {
    search: {
      versioned: true, // Enable versioned search
    },
  },
});
```

---

## Next Steps

- Explore [Built-in Components](./built-in-components.md)
- Learn about [Build Extensions](./build-extensions.md)
- Read about [Custom Search](./custom-search.md)

---

::: tip Best Practices
- Always maintain at least one LTS version
- Provide clear migration guides for each version
- Automate version creation process
- Keep version URL structure consistent
- Add clear warning banners for old versions
:::

::: warning Common Pitfalls
- Don't forget to update internal links
- Don't mix content between versions
- Don't maintain all versions indefinitely
- Don't use ambiguous version labels
- Don't forget to update search indexes
:::

::: info Resources
- [Semantic Versioning](https://semver.org/)
- [Documentation Versioning Best Practices](https://www.writethedocs.org/)
- [Rspress Configuration Reference](https://rspress.dev/api/config)
:::