diff --git a/recommended.code-workspace b/recommended.code-workspace index ce0d89eb34..015d276fc0 100644 --- a/recommended.code-workspace +++ b/recommended.code-workspace @@ -32,12 +32,9 @@ "typescriptreact", "graphql" ], - "vscode-vale.path": "${workspaceFolder}/node_modules/.bin/commercetools-vale", - "vscode-vale.fileExtensions": [ - "md", - "markdown", - "mdx" - ], + "vale.core.useCLI": true, + "vale.valeCLI.path": "${workspaceFolder}/node_modules/.bin/commercetools-vale-bin", + "vale.valeCLI.config": "${workspaceFolder}/node_modules/@commercetools-docs/writing-style/.vale.ini", "spellright.notificationClass": "error", "spellright.language": [ "en" @@ -58,7 +55,8 @@ ], "url": "./packages/application-config/schema.json" } - ] + ], + "typescript.tsdk": "node_modules/typescript/lib" }, "extensions": { "recommendations": [ diff --git a/website/src/content/api-reference/application-config.mdx b/website/src/content/api-reference/application-config.mdx index 277e75b092..a5d6716b78 100644 --- a/website/src/content/api-reference/application-config.mdx +++ b/website/src/content/api-reference/application-config.mdx @@ -623,7 +623,7 @@ You can also pass multiple references to the same value: -This feature is available from version `>= 20.8.0`. +This feature is available from version `20.8.0` onwards. @@ -652,7 +652,7 @@ The reference placeholder assumes that the Custom Application has the translatio -This feature is available from version `>= 20.8.0`. +This feature is available from version `20.8.0` onwards. diff --git a/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx b/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx index 991370cb88..3541c437aa 100644 --- a/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx +++ b/website/src/content/api-reference/commercetools-frontend-application-shell-connectors.mdx @@ -215,6 +215,34 @@ This component must be defined in a parent component where children of this comp | `skip` | `boolean` | - | - | false | Disables loading images configuration. | +### useProjectExtensionImageRegex + +A React hook that allows accessing the project images configuration. + +```jsx highlightLines="4-6" +import { useProjectExtensionImageRegex } from '@commercetools-frontend/application-shell-connectors'; + +function MyComponent() { + const { isLoading, imageRegex } = useProjectExtensionImageRegex(); + + if (isLoading) return ; + + return ( +
+

Project images regex: {JSON.stringify(imageRegex)}

+
+ ); +} + +function MyApp() { + return ( + + + + ); +} +``` + ### GetProjectExtensionImageRegex Use this component to access the project images configuration, using a `render` prop function. diff --git a/website/src/content/concepts/integrate-with-your-own-api.mdx b/website/src/content/concepts/integrate-with-your-own-api.mdx index c57d8bf192..c313924ee0 100644 --- a/website/src/content/concepts/integrate-with-your-own-api.mdx +++ b/website/src/content/concepts/integrate-with-your-own-api.mdx @@ -37,7 +37,7 @@ To facilitate the usage of the [built-in Apollo client and the SDK actions](/dev -This feature is available from version `>= 21.8.0`. +This feature is available from version `21.8.0` onwards. @@ -57,7 +57,7 @@ For example, given the forward-to URL `https://my-custom-app.com/api/123`, the ` -This feature is available from version `>= 20.2.0`. +This feature is available from version `20.2.0` onwards. diff --git a/website/src/content/development/adding-typescript.mdx b/website/src/content/development/adding-typescript.mdx new file mode 100644 index 0000000000..cb02e20c9a --- /dev/null +++ b/website/src/content/development/adding-typescript.mdx @@ -0,0 +1,101 @@ +--- +title: Adding TypeScript +--- + +[TypeScript](https://www.typescriptlang.org/) is a typed superset of JavaScript that compiles to plain JavaScript. + +Custom Applications have full support for developing applications in TypeScript. + + + +This feature is available from version `21.8.0` onwards. + + + +To start a new Custom Application project with TypeScript, you can use the TypeScript starter template: + +```console noPromptLines="2-3" +npx @commercetools-frontend/create-mc-app@latest \ + my-new-custom-application-project \ + --template starter-typescript +``` + +The TypeScript starter template is the same as the standard JavaScript starter template in terms of functionality but it also includes the additional TypeScript setup. + +# Configuration + +Every TypeScript project requires a `tsconfig.json` file to instruct TypeScript how to compile the project. + +Therefore, we provide a base TSConfig to be used in your `tsconfig.json` file: + +```json +{ + "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json" +} +``` + +Furthermore, we provide a `client.d.ts` declaration file with some basic type shims for importing media assets: + +- `.mod.css` and `.module.css` +- `.png` +- `.svg` + +You can include this using the TypeScript triple-slash directives: + +```ts +/// +``` + + + +By default, this is included in the TypeScript starter template `src/index.tsx` entry point file. + + + +You can also include this in the `tsconfig.json` file in the `compilerOptions.types` field but we don't recommend +doing so unless you are very familiar with the [implications of using the `types` field](https://www.typescriptlang.org/tsconfig#types). + +Additional adjustments to other config files are also required, in particular: + +- `.prettierrc`: use the `typescript` parser. +- `jest.test.config.js`: use the `@commercetools-frontend/jest-preset-mc-app/typescript` preset. +- `jest.eslint.config.js`: include the file extensions `ts` and `tsx` in `moduleFileExtensions`, then `/**/*.ts` and `/**/*.tsx` in `testMatch`. + + + +The TypeScript setup is already preconfigured when using the TypeScript starter template. Consider this document as a reference to match your setup. + + + +# Migrate to TypeScript + +If you have an existing Custom Application project and want to migrate to TypeScript, you should do the following: + +* Install the `typescript` dependency. +* Add a `tsconfig.json` file. See [configuration](#configuration) for the tooling setup. +* Migrate the JavaScript files to TypeScript, using either `.ts` or `.tsx` (if a file contains JSX syntax). + + + + Migrating source files to TypeScript can be done incrementally. We recommend starting from the "leaf files" and working up to the application entry point. + The [migrating from JavaScript documentation](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html) can help you set up a basic plan. + + All UI Kit and ApplicationKit packages provide declaration files and export useful types when necessary. + + During migration you might need to loosen up the types strictness, for example by allowing explicit `any` types. + + ```json title="tsconfig.json" + { + "extends": "@commercetools-frontend/application-config/tsconfig-mc-app.json", + "compilerOptions": { + "noExplicitAny": false, + "strict": false + } + } + ``` + + You should revert these once migration is complete, as using `any` should be avoided. + + + +* Add the script command `"typecheck": "tsc --noEmit"` to your `package.json` to run the type checks of the application. diff --git a/website/src/content/development/index.mdx b/website/src/content/development/index.mdx index df24bb968f..f0f8941d22 100644 --- a/website/src/content/development/index.mdx +++ b/website/src/content/development/index.mdx @@ -49,6 +49,12 @@ In particular, we'll be going through the following topics: > Learn more about implementing translations in your Custom Application. + + Learn more about developing your Custom Application using TypeScript. + Local development and login are only allowed for users being part of the `Administrators` Team of your Organization. Therefore, choose a Project that is part of an Organization where you are an administrator of. diff --git a/website/src/data/navigation.yaml b/website/src/data/navigation.yaml index df4ced9142..a5c08333f2 100644 --- a/website/src/data/navigation.yaml +++ b/website/src/data/navigation.yaml @@ -38,6 +38,8 @@ path: /development/translations - title: Permissions path: /development/permissions + - title: Adding TypeScript + path: /development/adding-typescript - title: Going to Production path: /development/going-to-production - chapter-title: Deployment Examples diff --git a/website/src/releases/2020-06/hostname-migration.mdx b/website/src/releases/2020-06/hostname-migration.mdx index a1614a95b9..56946e7402 100644 --- a/website/src/releases/2020-06/hostname-migration.mdx +++ b/website/src/releases/2020-06/hostname-migration.mdx @@ -71,7 +71,7 @@ For example: In production, the `` takes care of inferring the correct [Merchant Center Gateway API hostname](/concepts/merchant-center-api#hostnames) based on the Merchant Center hostname that the user is logged into. This results in the Custom Application to work in both new and legacy hostnames, even though the `mcApiUrl` is configured to a specific value. -This feature is available from version `>= 16.2.1`. +This feature is available from version `16.2.1` onwards. diff --git a/website/src/releases/2022-07/release-v21.8.mdx b/website/src/releases/2022-07/release-v21.8.mdx new file mode 100644 index 0000000000..d8ce34dea5 --- /dev/null +++ b/website/src/releases/2022-07/release-v21.8.mdx @@ -0,0 +1,48 @@ +--- +date: 2022-07-04 +title: Custom Applications v21.8 +description: The Application Kit packages have been released with several new features. +type: feature +topics: + - CLI + - Configuration + - Templates + - UI Components +--- + +The Application Kit packages have been released with a minor version `v21.8`. + +This release includes several new features that we would like to present: + +* Official support for developing Custom Applications in [TypeScript](https://www.typescriptlang.org/), including a new starter template. Read more about TypeScript in the [Adding TypeScript](/development/adding-typescript) page. +* New policy option for configuring the `audience` field when [integrating your Custom Application with an external API](/concepts/integrate-with-your-own-api#configuring-the-audience-policy). +* Improved accessibility of different elements using ARIA attributes. +* Simpler and more readable list of time zone data, available from the `@commercetools-frontend/l10n` package. +* New React hook `useProjectExtensionImageRegex` for accessing the project images configuration, available from the `@commercetools-frontend/application-shell-connectors` package. + +As always, if you have questions or feedback you can open a [GitHub Discussion](https://github.com/commercetools/merchant-center-application-kit/discussions) or a [GitHub Issue](https://github.com/commercetools/merchant-center-application-kit/issues). + + + +# Deprecations + +The `mc-scripts` CLI has deprecated some entry points. + +Importing the function `createPostcssConfig` from the main entry point `@commercetools-frontend/mc-scripts` is now deprecated. Use the entry point `@commercetools-frontend/mc-scripts/postcss` instead. + +```diff +const { + createPostcssConfig, +-} = require('@commercetools-frontend/mc-scripts'); ++} = require('@commercetools-frontend/mc-scripts/postcss'); +``` + +Importing the functions `createWebpackConfigForDevelopment` and `createWebpackConfigForProduction` from the main entry point `@commercetools-frontend/mc-scripts` is now deprecated. Use the entry point `@commercetools-frontend/mc-scripts/webpack` instead. + +```diff +const { + createWebpackConfigForDevelopment, + createWebpackConfigForProduction, +-} = require('@commercetools-frontend/mc-scripts'); ++} = require('@commercetools-frontend/mc-scripts/webpack'); +```