# Upgrading

This page documents breaking changes, new features, and migration steps for releases that require your attention when upgrading. New versions are listed from newest to oldest.

## v2.0.0

v2 is a major release that streamlines the module's configuration and storage layers. Module declarations are now consistently array-based, custom database tables are powered by [Drizzle ORM](https://orm.drizzle.team/), and the package's public configuration.customTables = {
  schema,
  migrationFolder: './migrations', // SQLite / PostgreSQL
  d1Migrations: migrations,        // Cloudflare D1
};

// access the Drizzle instance
const db = crowdinApp.storage.db;
```

Migration:

1. Install `drizzle-orm` and `drizzle-kit`.
2. Define your tables as a Drizzle schema and generate migrations (or declare them manually for D1).
3. Register them via `configuration.customTables` and rewrite custom queries with the Drizzle API.

See the [Database guide](/app-project-module/database/#custom-database-tables) for full details.

### Package Import Paths Reworked

Public import subpaths have been consolidated. Only documented paths are supported; internal paths may change without notice.

Removed:

- `@crowdin/app-project-module/out/*` - internal build output, no longer exposed
- `@crowdin/app-project-module/storage`
- `@crowdin/app-project-module/modules/integration/util`

Added:

- `@crowdin/app-project-module/test` - app testing utilities

Migration: import `Storage` and other types from the main entrypoint `@crowdin/app-project-module`, and replace any `/out/*` imports with the corresponding public subpath. See [supported import paths](/app-project-module/installation/#supported-import-paths).

### AI Tools Modules Removed

The `aiTools` and `aiToolsWidget` modules have been removed. Remove these options from your configuration; there is no direct replacement.

### MySQL Storage Removed

MySQL is no longer a supported storage backend. The `mysqlConfig` option has been removed. Supported databases are now SQLite (default), PostgreSQL, and Cloudflare D1.

Migration: switch to PostgreSQL (or SQLite). There is no automatic MySQL migration - move your data to a supported database manually.

## v1.9.0

Crowdin app helpers that previously lived in the standalone npm package [`@crowdin/crowdin-apps-functions`](https://github.com/crowdin/crowdin-apps-functions) are now shipped with this module. Prefer the built-in entry points so your app stays aligned with the Apps SDK version you already depend on.

### Migration from `@crowdin/crowdin-apps-functions`

- **Action required:** Remove `@crowdin/crowdin-apps-functions` from your dependencies and replace imports with the subpaths below.
- **Token helpers** (OAuth, app tokens, JWT validation, Crowdin id parsing) - import from `@crowdin/app-project-module/functions/token`.
- **Crowdin API helpers** (files, folders, translations, webhooks, subscriptions) - import from `@crowdin/app-project-module/functions/crowdin`.

The API surface matches what the standalone library provided; see [App Functions](/app-project-module/reference/app-functions/) for exports, subpath names, and usage examples.

## v1.3.0

The project now uses `react-jsonschema-form` v6. Modules that [define UI](/app-project-module/user-interface/) as a `formSchema` should review the breaking changes below.

### Potential Breaking Changes

- `enumNames` - Use `ui:enumNames` in `UiSchema` instead of `enumNames` on the schema
- `idSchema`, `formContext`, `classNames`, themes, callbacks - see the upgrade guide for details

See the [6.x Upgrade Guide](https://rjsf-team.github.io/react-jsonschema-form/docs/migration-guides/v6.x%20upgrade%20guide/) for full details.

## v1.0.0

Major release introducing Cloudflare Workers support, Express 5 upgrade, and architectural improvements.

### Breaking Changes

#### Express 5 Upgrade

- **Action required:** Test your application thoroughly after upgrading
- **Potential issues:** Some third-party middleware may need updates, subtle error handling differences

#### AWS SDK Dependencies

- **Action required:** If using S3 file processing, manually install:
  ```bash
  npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
  ```
- **Benefit:** Smaller bundle size for apps not using AWS S3

#### Methods signature updates

All functions now follow the **parameter object** pattern (also known as an *options object* or *named parameters via destructuring*).

This means functions that previously took several positional arguments now accept a single `options` object - destructured in the signature - which improves readability and makes optional parameters easier to manage.

Before:

```ts
// positional parameters
getCrowdinFiles: (projectId: number, client: Crowdin, appRootFolder?: SourceFilesModel.Directory, config?: any, mode?: CrowdinFilesLoadMode) => Promise<TreeItem[]>;
```

After:

```ts
// parameter object (destructured)
getCrowdinFiles: (options: {
  projectId: number;
  client: Crowdin;
  rootFolder?: SourceFilesModel.Directory;
  settings?: any;
  mode?: CrowdinFilesLoadMode;
}) => Promise<TreeItem[]>;
```

Example:

Before:

```js
configuration.projectIntegration.cronJobs = [
  {
    expression: '*/10 * * * * *',
    task: (projectId, credentials, rootFolder, settings) => {
      console.log(`Running background task for project: ${projectId}`);
      console.log(`Api credentials: ${JSON.stringify(credentials)}`);
      console.log(`App config: ${JSON.stringify(settings)}`);
      console.log(rootFolder ? JSON.stringify(rootFolder) : 'No root folder');
    }
  }
];
```

After:

```js
configuration.projectIntegration.cronJobs = [
  {
    expression: '*/10 * * * * *',
    task: ({ projectId, credentials, rootFolder, settings } = {}) => {
      console.log(`Running background task for project: ${projectId}`);
      console.log(`Api credentials: ${JSON.stringify(credentials)}`);
      console.log(`App config: ${JSON.stringify(settings)}`);
      console.log(rootFolder ? JSON.stringify(rootFolder) : 'No root folder');
    }
  }
];
```

List of all affected functions (some functions that already used parameter objects were renamed or had parameter names updated):

#### Updated functions (now accept a parameter object)

These functions now accept a single destructured `options` object (e.g., `fn({ a, b, c })`).

##### Global
- `decryptCrowdinConnection`
- `establishCrowdinConnection`
- `log`
- `onError`
- `onUninstall`
- `saveMetadata`

##### Per-module (grouped by module)
- **aiPromptProvider**
  - `compile`
- **aiProvider**
  - `chatCompletions`
- **aiRequestPreCompile**
  - `processRequest`
  - `processStream`
- **aiTools**
  - `toolCalls`
- **automationAction**
  - `execute`
  - `validateSettings`
- **customMT**
  - `translate`

##### File processing (modules: `customFileFormat`, `filePreImport`, `filePostImport`, `filePreExport`, `filePostExport`, `fileTranslationsAlignmentExport`)
- `buildFile`
- `exportStrings`
- `fileProcess`
- `parseFile`

##### projectIntegration
- `crowdinWebhookInterceptor`
- `crowdinWebhooks`
- `getAuthorizationUrl`
- `getConfiguration`
- `getCrowdinFiles`
- `getFileProgress`
- `getIntegrationFiles`
- `integrationWebhookInterceptor`
- `integrationWebhooks`
- `matchCrowdinFilesToIntegrationFiles`
- `normalizeSettings`
- `onLogout`
- `performGetTokenRequest` (`oauthLogin`)
- `performRefreshTokenRequest` (`oauthLogin`)
- `task`
- `updateCrowdin`
- `updateIntegration`
- `validateSettings`

### New Features

#### Cloudflare Workers Support

- **D1 Database:** `d1Config` for serverless SQL database
- **Custom Cron:** `cron` option for Workers scheduled events  
- **File Storage:** `fileStore` interface for external storage (S3, R2, etc.)
- **Assets:** `assetsConfig` for Workers Assets integration, `assetsPath` for custom static directory
- **Webhooks:** `deferResponse: true` required for proper Workers execution

### Migration Guide

1. **Update package.json:** `"@crowdin/app-project-module": "^1.0.0"`
2. **Install AWS SDK if needed:** (see breaking changes above)
3. **Test Express 5 compatibility**

### Dependencies

- **Updated:** Express 4 → 5, React 18 added (internal)
- **Moved to optional:** AWS SDK packages