@personio/scripts

A set of node scripts to auto-generate files. Currently, the library includes two: request and translations. See more information bellow.

Installation

Run

yarn add -D @personio/scripts

CLI options

-s, --script <script>        // *Required. The script you want to run. Can be either translations or request.

-o, --outputDir <directory>  // *Only valid for the request script. The path of the directory you want to generate the request helper files.
                             //  The default is src/helpers/request,

-i, --inputFile <type>       // *Only valid for the request script. The path of your openapi.yaml file.
                             //  The default is openapi.yaml

-n, --requestName <name>     // *Only valid for the request script. Create the request helper naming based on this options.
                             //  It accepts three variants: operationId, summary or url, Default is operationId.

--noResponseMocks            // *Only valid for the request script.
                             //  Disable the creation of the response mocks.

--pact                       // Only valid for the request script.
                            // Use to generate pact file

--retrieveDataFromResponse   // Only valid for the request script.
                             // Use if your project is using the retrieveDataFromResponse parameter in the @personio/requests config

-d, --domain <domain>        // *Required. Only valid for the translations script.
                             //  Your teams domain, where we can find the translations.json file.

--fromLocalPhraseServer      // *Only valid for the translations script.
                             //  Retrieves the translations from http://localhost:9800 instead of production.
                             //  Don't forget to run the synchronisation pipeline before going to production!

--fromLocalTranslationsFile <filepath> // *Only valid for the translations script.
                                       //  [DANGEROUS] Retrieves the translations from a local JSON file (in i18next format) instead of production.
                                       //  The usage of the `--fromLocalTranslationsFile` is dangerous since PhraseApp might
                                       //  not contain the keys provided in the input file. It's supposed to be used only by the tooling
                                       //  that ensures that all keys are in place (e.g. VSCode Personio Extension).

Description

As mentioned, we have two different scripts included in the library:

• translations
• request

translations

This script generates four files:

• __mocks__/translationsMock.ts file including all the english translations to be injected into your test configuration.
• config/translations.json file including the english translations in JSON format. It can be served locally for your i18n configuration to speed up development.
• translations.ts file including the types from the translations of your team's domain.
• react18next-resources.d.ts file that declares your react18next resource types to enforce type safety on the translation key usage. Note : This will only works for react-18next version 11 and upwards.

Example

 personio-scripts -s translations -d recruiting

• After running the script, you can check the generated files in the path src/translations.ts and the src/__mocks__/translationsMock.ts

request

This script generates three files, all based on the openApi.yaml.

• types.ts file, which includes:
  • query keys enum for using with react-query
  • the types from your request responses
• requestHelper.ts file with functions wrapped in the @personio/request library based on the APIs URL.
• responseMocks.ts file with all the response examples provided. NOTE: Double check the name of all your examples as it's required to have a valid javascript syntax otherwise the script will fail.

Example

 personio-scripts -s request -n summary

• After running the script and you haven't changed the output directory, you can check the generated files in the path src/helper/request/requestHelper.ts and the src/helper/request/types.ts.

  Note:

• The -n, --requestName <name> option accepts three variants: operationId, summary or url.

  • operationId: Takes this property as is. If you intend to use it, you should make sure this is a valid function name for javascript. For instance, the property is already in camelCase.
  • summary: Takes the summary property, remove the spacing and prepends the http method. Eg:

    • get:
        summary: Preferences settings

    • the function will be called: getPreferencesSettings
  • url: Takes the url, split based on the / ,takes the last 3 names and prepends the http method. Eg:

    • /api/v1/preferences:
        get: ...

    • the function will be called: getApiV1Preferences