Skip to content

Add documentation for programmatic TypeScript usage #1010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 26, 2022
Merged

Add documentation for programmatic TypeScript usage #1010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions docs/developer-docs/latest/developer-resources/cli/CLI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
Expand Down Expand Up @@ -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>
Expand All @@ -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).
Expand Down
4 changes: 4 additions & 0 deletions docs/developer-docs/latest/development/backend-customization/models.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
120 changes: 31 additions & 89 deletions docs/developer-docs/latest/development/typescript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

```
3 changes: 1 addition & 2 deletions docs/developer-docs/latest/plugins/email.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down Expand Up @@ -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)
:::
Expand Down