typescript programmatic use

docs/developer-docs/latest/developer-resources/cli/CLI.md

@@ -6,7 +6,7 @@ canonicalUrl: https://docs.strapi.io/developer-docs/latest/developer-resources/c
 
 # Command Line Interface (CLI)
 
-Strapi comes with a full featured Command Line Interface (CLI) which lets you scaffold and manage your project in seconds. 
+Strapi comes with a full featured Command Line Interface (CLI) which lets you scaffold and manage your project in seconds.
 
 ::: note
 It is recommended to install Strapi locally only, which requires prefixing all of the following `strapi` commands with the package manager used for the project setup (e.g `npm run strapi help` or `yarn strapi help`) or a dedicated node package executor (e.g. `npx strapi help`).
@@ -230,7 +230,7 @@ strapi generate
 
 ## strapi templates:generate
 
-Create a template from the current strapi project
+Create a template from the current Strapi project.
 
 ```bash
 strapi templates:generate <path>
@@ -241,6 +241,23 @@ strapi templates:generate <path>
 
   Example: `strapi templates:generate ../strapi-template-name` will copy the required files and folders to a `template` directory inside `../strapi-template-name`
 
+## strapi ts:generate-types
+
+Generate [TypeScript](/developer-docs/latest/development/typescript.md) typings for the project schemas.
+
+```sh
+strapi ts:generate-types
+```
+
+* **strapi ts:generate-types --verbose**<br/>
+  Generate typings with the verbose mode enabled, displaying a detailed table of the generated schemas.
+* **strapi ts:generate-types --silent** or **strapi ts:generate-types -s**<br/>
+  Generate typings with the silent mode enabled, completely removing all the logs in the terminal.
+* **strapi ts:generate-types --out-dir &#60;path&#62;** or **strapi ts:generate-types -o &#60;path&#62;**<br/>
+  Generate typings specifying the output directory in which the file will be created.
+* **strapi ts:generate-types --file &#60;filename&#62;** or **strapi ts:generate-types -f &#60;filename&#62;**<br/>
+  Generate typings specifiying the name of the file to contain the types declarations.
+
 ## strapi routes:list
 
 Display a list of all the available [routes](/developer-docs/latest/development/backend-customization/routes.md).

docs/developer-docs/latest/development/backend-customization/models.md

@@ -34,6 +34,10 @@ The content-types has the following models files:
 
 These models files are stored in `./src/api/[api-name]/content-types/[content-type-name]/`, and any JavaScript or JSON file found in these folders will be loaded as a content-type's model (see [project structure](/developer-docs/latest/setup-deployment-guides/file-structure.md)).
 
+:::note
+In [TypeScript](/developer-docs/latest/development/typescript.md)-enabled projects schema typings can be generated using the `ts:generate-types` command.
+:::
+
 ### Components
 
 Component models can't be created with CLI tools. Use the [Content-type Builder](/user-docs/latest/content-types-builder/introduction-to-content-types-builder.md) or create them manually.

docs/developer-docs/latest/development/typescript.md

@@ -67,126 +67,68 @@ To experience TypeScript-based autocomplete while developing Strapi applications
 3. Choose `runLifecyclesfunction` from the list.
 4. When the `strapi.runLifecyclesFunctions` method is added, a list of available lifecycle types (i.e. `register`, `bootstrap` and `destroy`) are returned by the code editor. Use keyboard arrows to choose one of the lifecycles and the code will autocomplete.
 
-## Develop a plugin using TypeScript
-
-New plugins can be generated following the [plugins development documentation](/developer-docs/latest/development/plugins-development.md). There are 2 important distinctions for TypeScript applications:
-
-- After creating the plugin, run `yarn install` or `npm run install` in the plugin directory `src/admin/plugins/[my-plugin-name]` to install the dependencies for the plugin.
-- Run `yarn build` or `npm run build` in the plugin directory `src/admin/plugins/[my-plugin-name]` to build the admin panel including the plugin.
-
-::: note
-It is not necessary to repeat the `yarn install` or `npm run install` command after the initial installation. The `yarn build` or `npm run build` command is necessary to implement any plugin development that affects the admin panel.
-:::
-
-## Start Strapi programmatically
-
-Instantiating Strapi programmatically in a TypeScript project requires additional configurations to load everything correctly. The primary difference for TypeScript programmatic use is that the codebase and compiled code are stored in separate directories, whereas the same directory is used to read and write in native JavaScript.
-
-### Understand programatic use
-
-When instantiating Strapi programmatically using the default export of `@strapi/strapi`, different parameters such as the `app` directory and the `dist` directory can be passed. The `app` directory is the project root directory and `dist` is a subdirectory of `app`. The `dist` directory represents the compiled project, with the same directory structure as the `app` directory, and the `app` directory represents the codebase (TypeScript or JavaScript). The main differences are:
+## Generate typings for project schemas
 
-- When using the Content-type Builder to create, update, delete content types (or any other service that creates files), Strapi uses the `app` folder to write the files.
-- When reading what content types exist on the system Strapi reads the `dist` folder.
-- When the `develop` command is used only the `app` directory is watched. In TypeScript, a compilation will be triggered when a change is detected in the `app` directory and the output will be written to the `dist` directory.
+To generate typings for your project schemas use the [`ts:generate-types` CLI command](/developer-docs/latest/developer-resources/cli/CLI.md#strapi-ts-generate-types). The `ts:generate-types` command creates the file `schemas.d.ts`, at the project root, which stores the schema typings. The optional `--verbose` flag returns a detailed table of the generated schemas.
 
-::: note
-The public folder is considered static and thus ignores the  `app` and `dist` directories.
-:::
+To use `ts:generate-types`run the following code in a terminal at the project root:
 
-The default values for the `app` and `dist` directories are transformed and assigned using one of the following options:
-
-```js
-
-const resolveWorkingDirectories = opts => {
-  const cwd = process.cwd(); // Neither the appDir or distDir are passed. Both the appDir and distDir are set to process.cwd().
-
-  const appDir = opts.appDir ? path.resolve(cwd, opts.appDir) : cwd; // Only appDir is defined distDir matches appDir.
-
-  const distDir = opts.distDir ? path.resolve(cwd, opts.distDir) : appDir; // Only distDir is defined, appDir is set to process.cwd().
+<code-group>
+<code-block title="NPM">
 
-  return { appDir, distDir };
-}
+```sh
+npm run strapi ts:generate-types --verbose #optional flag
 
 ```
 
-For example, if the compiled code is stored in a separate directory (eg: when using TypeScript)  Strapi should be instantiated with a specific `distDir` value which matches the path of your build directory.
-
-::: caution
-Do not set the `appDir` to the `build` or `dist` directory as it could cause issues when the app tries to write some files.
-:::
-
-### Start Strapi programmatically examples
-
-Start Strapi for JavaScript applications:
+</code-block>
 
-```js
-const strapi = require('@strapi/strapi');
+<code-block title="YARN">
 
-strapi();
-// appDir => process.cwd() | distDir => process.cwd()
+```sh
+yarn strapi ts:generate-types --verbose #optional flag
 
 ```
 
-Start Strapi using a custom `dist` directory:
+</code-block>
+</code-group>
 
-```js
-const strapi = require('@strapi/strapi');
+## Develop a plugin using TypeScript
 
-strapi({ distDir: './dist' });
-// appDir => process.cwd() | distDir => './dist'
-```
+New plugins can be generated following the [plugins development documentation](/developer-docs/latest/development/plugins-development.md). There are 2 important distinctions for TypeScript applications:
 
-Start Strapi using custom `app` and `dist` directories:
+- After creating the plugin, run `yarn` or `npm install` in the plugin directory `src/admin/plugins/[my-plugin-name]` to install the dependencies for the plugin.
+- Run `yarn build` or `npm run build` in the plugin directory `src/admin/plugins/[my-plugin-name]` to build the admin panel including the plugin.
 
-```js
+::: note
+It is not necessary to repeat the `yarn` or `npm install` command after the initial installation. The `yarn build` or `npm run build` command is necessary to implement any plugin development that affects the admin panel.
+:::
 
-const strapi = require('@strapi/strapi');
+## Start Strapi programmatically
 
-strapi({ distDir: './dist' });
-// appDir => process.cwd() | distDir => './dist'
+To start Strapi programmatically in a TypeScript project the Strapi instance requires the compiled code location. This section describes how to set and indicate the compiled code directory.
 
-```
+### Use the `strapi()` factory
 
-Start Strapi using a custom `app` directory:
+Strapi can be run programmatically by using the `strapi()` factory. Since the code of TypeScript projects is compiled in a specific directory, the parameter `distDir` should be passed to the factory to indicate where the compiled code should be read:
 
 ```js
+// path: ./src/plugins/<plugin-name>/server/index.js 
 
 const strapi = require('@strapi/strapi');
 
-strapi({ appDir: './app' });
-// appDir => './app' | distDir => './app'
-
+const app = await strapi({ distDir: './dist' });
 ```
 
-### Use both JavaScript and TypeScript codebases when starting Strapi programmatically
+### Use the `strapi.compile()` function
 
-Adding the package `@strapi/typescript-utils` allows for both JavaScript and TypeScript codebases to be used programatically. A common use is for creating command line interface tools or developing a plugin. Examples of how to incorporate both code bases:
+The `strapi.compile()` function should be mostly used for developing tools that need to start a Strapi instance and detect whether the project includes TypeScript code. `strapi.compile()` automatically detects the project language. If the project code contains any TypeScript code, `strapi.compile()` compiles the code and returns a context with specific values for the directories that Strapi requires:
 
 ```js
-const tsUtils = require('@strapi/typescript-utils');
-const strapi = require('@strapi/strapi');
-
-const appDir = process.cwd();
-
-// Automatically detect if this is a Typescript project:
-const isTSProject = await tsUtils.isUsingTypeScript(appDir);
 
-// Resolve the directory containing the compilation output:
-const outDir = await tsUtils.resolveOutDir(appDir);
-
-if (isTSProject) {
-// If inside a Typescript project, compile the TypeScript code in the appDir:
-  await tsUtils.compile(appDir, {
-    watch: false,
-    configOptions: { options: { incremental: true } },
-  });
-}
-
-// If inside a Typescript project, use a custom dist directory, otherwise set it to appDir value: 
-const distDir = isTSProject ? outDir : appDir;
+const strapi = require('@strapi/strapi');
 
-// Start the app by providing the app and dist directories:
-const app = await strapi({ appDir, distDir }).load();
+const appContext = await strapi.compile();
+const app = await strapi(appContext);
 
 ```

docs/developer-docs/latest/plugins/email.md

@@ -107,6 +107,7 @@ When using community providers, pass the full package name to the `provider` key
 Here is an example of a configuration made for the provider [@strapi/provider-email-sendgrid](https://www.npmjs.com/package/@strapi/provider-email-sendgrid).
 
 **Path —** ``.
+
 <code-group>
 
 <code-block title="JAVASCRIPT">
@@ -162,8 +163,6 @@ export default = ({ env }) => ({
 
 </code-group>
 
-
-
 ::: tip
 If you're using a different provider depending on your environment, you can specify the correct configuration in `./config/env/${yourEnvironment}/plugins.js`. More info here: [Environments](/developer-docs/latest/setup-deployment-guides/configurations/optional/environment.md)
 :::