@intlayer/config 1.0.2 → 1.2.0

package/src/configFile/buildConfigurationFields.ts

@@ -9,13 +9,11 @@ import {
   SERVER_SET_COOKIE,
 } from '../defaultValues/middleware';
 import {
-  BUNDLE_DIR_NAME,
   CONTENT_DIR_NAME,
   DICTIONARIES_DIR_NAME,
   FILE_EXTENSIONS,
   RESULT_DIR_NAME,
   EXCLUDED_PATHS,
-  BUNDLE_FILE_EXTENSION,
   TYPES_DIR_NAME,
   MAIN_DIR_NAME,
   MODULE_AUGMENTATION_DIR_NAME,
@@ -35,17 +33,23 @@ import type { GetConfigurationOptions } from './getConfiguration';
 
 let storedConfiguration: IntlayerConfig;
 
+// @TODO - Add possibility of directories configurations to be arrays to allow multiple packages management
+
 const buildInternationalizationFields = (
   customConfiguration?: Partial<InternationalizationConfig>
 ): InternationalizationConfig => ({
   /**
-   * Internationalization configuration
+   * Locales available in the application
+   *
+   * Default: ['en']
    */
-
-  // Locales available in the application
   locales: customConfiguration?.locales ?? LOCALES,
 
-  // Default locale of the application for fallback
+  /**
+   * Default locale of the application for fallback
+   *
+   * Default: 'en'
+   */
   defaultLocale: customConfiguration?.defaultLocale ?? DEFAULT_LOCALE,
 });
 
@@ -53,25 +57,61 @@ const buildMiddlewareFields = (
   customConfiguration?: Partial<MiddlewareConfig>
 ): MiddlewareConfig => ({
   /**
-   * Middleware configuration
+   * Header name to get the locale
+   *
+   * Default: 'x-intlayer-locale'
    */
-
-  // Header name to get the locale
   headerName: customConfiguration?.headerName ?? HEADER_NAME,
 
-  // Cookie name to get the locale
+  /**
+   * Cookie name to get the locale
+   *
+   * Default: 'intlayer-locale'
+   */
   cookieName: customConfiguration?.cookieName ?? COOKIE_NAME,
 
-  // Prefix the default locale in the URL
+  /**
+   * Prefix the default locale in the URL
+   *
+   * Default: true
+   */
   prefixDefault: customConfiguration?.prefixDefault ?? PREFIX_DEFAULT,
 
-  // Base path
+  /**
+   * Base path of the application URL
+   *
+   * Default: ''
+   *
+   * Example:
+   * - If the application is hosted at https://example.com/my-app
+   * - The base path is '/my-app'
+   * - The URL will be https://example.com/my-app/en
+   * - If the base path is not set, the URL will be https://example.com/en
+   */
   basePath: customConfiguration?.basePath ?? BASE_PATH,
 
-  // Set cookie on server
+  /**
+   * Rule to set the cookie on the server
+   * - 'always': Set the cookie on every request
+   * - 'never': Never set the cookie
+   */
   serverSetCookie: customConfiguration?.serverSetCookie ?? SERVER_SET_COOKIE,
 
-  // No prefix
+  /**
+   * No prefix in the URL
+   * - true: No prefix in the URL
+   * - false: Prefix in the URL
+   *
+   * Example:
+   * - If the application is hosted at https://example.com/my-app
+   * - The base path is '/my-app'
+   * - The URL will be https://example.com/my-app/en
+   * - If the base path is not set, the URL will be https://example.com/en
+   * - If no prefix is set, the URL will be https://example.com/en
+   * - If the no prefix is set to true, the URL will be https://example.com
+   *
+   * Default: false
+   */
   noPrefix: customConfiguration?.noPrefix ?? NO_PREFIX,
 });
 
@@ -80,61 +120,186 @@ const buildContentFields = (
 ): ContentConfig => {
   const notDerivedContentConfig: BaseContentConfig = {
     /**
-     * Content configurations
+     * File extensions of content to look for to build the dictionaries
+     *
+     * - Default: ['.content.ts', '.content.js', '.content.json']
+     *
+     * - Example: ['.data.ts', '.data.js', '.data.json']
+     *
+     * Note:
+     * - Can exclude unused file extensions to improve performance
+     * - Avoid using common file extensions like '.ts', '.js', '.json' to avoid conflicts
      */
-
-    // File extensions of content to look for
     fileExtensions: customConfiguration?.fileExtensions ?? FILE_EXTENSIONS,
 
-    // Directory name of the project
+    /**
+     * Absolute path of the directory of the project
+     * - Default: process.cwd()
+     * - Example: '/path/to/project'
+     *
+     * Will be used to resolve all intlayer directories
+     *
+     * Note:
+     * - The base directory should be the root of the project
+     * - Can be changed to a custom directory to externalize either the content used in the project, or the intlayer application from the project
+     */
     baseDir: customConfiguration?.baseDir ?? process.cwd(),
 
-    // Directory name where the content is stored
+    /**
+     * Directory name where the content is stored
+     *
+     * Default: 'src'
+     *
+     * Example:
+     *  - 'data' -> '/path/to/project/data'
+     *  - 'content' -> '/path/to/project/content'
+     *  - 'locales' -> '/path/to/project/locales'
+     *
+     * Note: If this directory is not at the base directory level, update the contentDir field instead
+     */
     contentDirName: customConfiguration?.contentDirName ?? CONTENT_DIR_NAME,
 
-    // Result directory name
+    /**
+     * Directory name where the result will be stored
+     *
+     * Default: '.intlayer'
+     *
+     * Example:
+     *  - '.next'
+     *  - 'outputOFIntlayer'
+     *
+     * Note: If this directory is not at the base directory level, update the resultDir field instead
+     */
     resultDirName: customConfiguration?.resultDirName ?? RESULT_DIR_NAME,
 
-    // Module augmentation directory name
+    /**
+     *
+     * Directory name where the module augmentation will be stored
+     *
+     * Module augmentation allow better IDE suggestions and type checking
+     *
+     * Default: 'types'
+     *
+     * Example: 'intlayer-types'
+     *
+     * Note:
+     * - If this path changed, be sure to include it from the tsconfig.json file
+     * - If this directory is not at the base directory level, update the moduleAugmentationDir field instead
+     */
     moduleAugmentationDirName:
       customConfiguration?.moduleAugmentationDirName ??
       MODULE_AUGMENTATION_DIR_NAME,
+    // @TODO: Make Module Augmentation optional by adding a flag in the configuration
 
-    // Bundle directory name
-    bundleDirName: customConfiguration?.bundleDirName ?? BUNDLE_DIR_NAME,
-
-    // Bundle file extension
-    bundleFileExtension:
-      customConfiguration?.bundleFileExtension ?? BUNDLE_FILE_EXTENSION,
-
-    // Dictionary directory name
+    /**
+     * Related to the intlayer result directory
+     *
+     * Directory name where the dictionaries will be stored
+     *
+     * Default: 'dictionary'
+     *
+     * Example: 'translations'
+     *
+     * Note:
+     * - If this directory is not at the result directory level, update the dictionariesDir field instead
+     *
+     */
     dictionariesDirName:
       customConfiguration?.dictionariesDirName ?? DICTIONARIES_DIR_NAME,
 
-    // Types directory name
+    /**
+     *  Related to the intlayer result directory
+     *
+     * Directory name where the dictionaries types will be stored
+     *
+     * Default: 'types'
+     *
+     * Example: 'intlayer-types'
+     *
+     * Note:
+     * - If this directory is not at the result directory level, update the typesDir field instead
+     *
+     */
     typeDirName: customConfiguration?.typeDirName ?? TYPES_DIR_NAME,
 
-    // Main directory name
+    /**
+     * Related to the intlayer result directory
+     *
+     * Directory name where the main files will be stored
+     *
+     * Default: 'main'
+     *
+     * Example: 'intlayer-main'
+     *
+     * Note:
+     * - If this directory is not at the result directory level, update the mainDir field instead
+     */
     mainDirName: customConfiguration?.mainDirName ?? MAIN_DIR_NAME,
 
-    // Directories to exclude
+    /**
+     * Should exclude some directories from the content search
+     *
+     * Default: ['node_modules']
+     *
+     * Not used yet
+     * @TODO Implement the exclusion or remove it
+     */
     excludedPath: customConfiguration?.excludedPath ?? EXCLUDED_PATHS,
   };
 
   const baseDirDerivedConfiguration: BaseDerivedConfig = {
-    // Directory where the content is stored
+    /**
+     * Directory where the content is stored
+     *
+     * Relative to the base directory of the project
+     *
+     * Default: {{baseDir}} / {{contentDirName}}
+     *
+     * Example: '/path/to/project/src'
+     *
+     * Note:
+     * - Can be changed to a custom directory to externalize the content used in the project
+     * - If the content is not at the base directory level, update the contentDirName field instead
+     */
     contentDir: join(
       notDerivedContentConfig.baseDir,
       notDerivedContentConfig.contentDirName
     ),
 
-    // Directory where the result will be stored
+    /**
+     * Directory where the result will be stored
+     *
+     * Relative to the base directory of the project
+     *
+     * Default: {{baseDir}} / {{resultDirName}}
+     *
+     * Example: '/path/to/project/.intlayer'
+     *
+     * Note:
+     * - Can be changed to a custom directory to externalize the intlayer application from the project
+     * - If the result is not at the base directory level, update the resultDirName field instead
+     */
     resultDir: join(
       notDerivedContentConfig.baseDir,
       notDerivedContentConfig.resultDirName
     ),
 
-    // Directory where the module augmentation will be stored
+    /**
+     * Directory where the module augmentation will be stored
+     *
+     * Module augmentation allow better IDE suggestions and type checking
+     *
+     * Relative to the base directory of the project
+     *
+     * Default: {{baseDir}} / {{moduleAugmentationDirName}}
+     *
+     * Example: '/path/to/project/types'
+     *
+     * Note:
+     * - If this path changed, be sure to include it from the tsconfig.json file
+     * - If the module augmentation is not at the base directory level, update the moduleAugmentationDirName field instead
+     *
+     */
     moduleAugmentationDir: join(
       notDerivedContentConfig.baseDir,
       notDerivedContentConfig.moduleAugmentationDirName
@@ -142,25 +307,56 @@ const buildContentFields = (
   };
 
   const resultDirDerivedConfiguration: ResultDirDerivedConfig = {
-    // Directory where the bundle will be stored
-    bundleDir: join(
-      baseDirDerivedConfiguration.resultDir,
-      notDerivedContentConfig.bundleDirName
-    ),
-
-    // Directory where the dictionaries will be stored
+    /**
+     * Directory where the dictionaries will be stored
+     *
+     * Relative to the result directory
+     *
+     * Default: {{resultDir}} / {{dictionariesDirName}}
+     *
+     * Example: '/path/to/project/.intlayer/dictionary'
+     *
+     * Note:
+     * - If the types are not at the result directory level, update the dictionariesDirName field instead
+     * - The dictionaries are stored in JSON format
+     * - The dictionaries are used to translate the content
+     * - The dictionaries are built from the content files
+     */
     dictionariesDir: join(
       baseDirDerivedConfiguration.resultDir,
       notDerivedContentConfig.dictionariesDirName
     ),
 
-    // Directory where the types will be stored
+    /**
+     * Directory where the dictionaries types will be stored
+     *
+     * Relative to the result directory
+     *
+     * Default: {{resultDir}} / {{typeDirName}}
+     *
+     * Example: '/path/to/project/.intlayer/types'
+     *
+     * Note:
+     * - If the types are not at the result directory level, update the typesDirName field instead
+     */
     typesDir: join(
       baseDirDerivedConfiguration.resultDir,
       notDerivedContentConfig.typeDirName
     ),
 
-    // Directory where the main files will be stored
+    /**
+     * Directory where the main files will be stored
+     *
+     * Relative to the result directory
+     *
+     * Default: {{resultDir}} / {{mainDirName}}
+     *
+     * Example: '/path/to/project/.intlayer/main'
+     *
+     * Note:
+     *
+     * - If the main files are not at the result directory level, update the mainDirName field instead
+     */
     mainDir: join(
       baseDirDerivedConfiguration.resultDir,
       notDerivedContentConfig.mainDirName
@@ -168,17 +364,29 @@ const buildContentFields = (
   };
 
   const patternsConfiguration: PatternsContentConfig = {
-    // Pattern of files to watch
+    /**
+     * Pattern of files to watch
+     *
+     * Default: ['/**\/*.content.ts', '/**\/*.content.js', '/**\/*.content.json']
+     */
     watchedFilesPattern: notDerivedContentConfig.fileExtensions.map(
       (ext) => `/**/*${ext}`
     ),
 
-    // Pattern of files to watch including the relative path
+    /**
+     * Pattern of files to watch including the relative path
+     *
+     * Default: ['{{contentDir}}/**\/*.content.ts', '{{contentDir}}/**\/*.content.js', '{{contentDir}}/**\/*.content.json']
+     */
     watchedFilesPatternWithPath: notDerivedContentConfig.fileExtensions.map(
       (ext) => `${baseDirDerivedConfiguration.contentDir}/**/*${ext}`
     ),
 
-    // Pattern of files to output
+    /**
+     * Pattern of dictionary to interpret
+     *
+     * Default: '{{dictionariesDir}}/**\/*.json'
+     */
     outputFilesPatternWithPath: `${resultDirDerivedConfiguration.dictionariesDir}/**/*.json`,
   };
 
@@ -190,6 +398,9 @@ const buildContentFields = (
   };
 };
 
+/**
+ * Build the configuration fields by merging the default values with the custom configuration
+ */
 export const buildConfigurationFields = (
   options: GetConfigurationOptions,
   customConfiguration?: CustomIntlayerConfig

package/src/configFile/getConfiguration.ts

@@ -19,6 +19,9 @@ const defaultOptions: GetConfigurationOptions = {
   verbose: false,
 };
 
+/**
+ * Get the configuration for the intlayer by reading the configuration file (e.g. intlayer.config.js)
+ */
 export const getConfiguration = (
   options?: Partial<GetConfigurationOptions>
 ): IntlayerConfig => {

package/src/configFile/index.ts

@@ -1 +1,2 @@
 export * from './getConfiguration';
+export * from './searchConfigurationFile';

package/src/configFile/loadConfigurationFile.ts

@@ -34,6 +34,19 @@ const transformationOption: BuildOptions = {
   bundle: true,
 };
 
+const filterValidConfiguration = (
+  configuration: CustomIntlayerConfig
+): CustomIntlayerConfig => {
+  // @TODO Implement filtering of valid configuration
+  return configuration;
+};
+
+/**
+ * Load the configuration file from the given path
+ * Example of configuration file: intlayer.config.js
+ *
+ * Accepts JSON, JS, MJS and TS files as configuration
+ */
 export const loadConfigurationFile = (
   configFilePath: string
 ): CustomIntlayerConfig | undefined => {
@@ -90,7 +103,12 @@ export const loadConfigurationFile = (
       customConfiguration = sandboxContext.module.exports;
     }
 
-    return customConfiguration;
+    if (typeof customConfiguration === 'undefined') {
+      console.error('Configuration file could not be loaded.');
+      return undefined;
+    }
+
+    return filterValidConfiguration(customConfiguration);
   } catch (error) {
     console.error('Error:', error);
   }

package/src/configFile/searchConfigurationFile.ts

@@ -16,6 +16,17 @@ type SearchConfigurationFileResult = {
   numCustomConfiguration: number;
 };
 
+/**
+ * Search for the configuration file in the given path
+ *
+ * List of detected configuration files:
+ * - intlayer.config.ts
+ * - intlayer.config.js
+ * - intlayer.config.json
+ * - intlayer.config.cjs
+ * - intlayer.config.mjs
+ * - .intlayerrc
+ */
 export const searchConfigurationFile = (
   configFilePath: string
 ): SearchConfigurationFileResult => {

package/src/defaultValues/server.ts

@@ -7,10 +7,6 @@ export const RESULT_DIR_NAME = '.intlayer';
 
 export const MODULE_AUGMENTATION_DIR_NAME = 'types';
 
-export const BUNDLE_DIR_NAME = 'bundle';
-
-export const BUNDLE_FILE_EXTENSION = '.bundle.js';
-
 export const DICTIONARIES_DIR_NAME = 'dictionary';
 
 export const TYPES_DIR_NAME = 'types';

package/src/envVariables/detectPlatform.ts

@@ -0,0 +1,37 @@
+export type Platform = 'next' | 'vite' | 'react_app' | 'unknown';
+export type ViteEnvVar = { env: Record<string, string> };
+
+export const getPlatform = (): Platform => {
+  if (typeof process.env.NEXT_PUBLIC_INTLAYER_DEFAULT_LOCALE === 'string') {
+    // Likely Next.js
+    return 'next';
+  } else if (
+    typeof process.env.REACT_APP_INTLAYER_DEFAULT_LOCALE === 'string'
+  ) {
+    // Likely Create React App
+    return 'react_app';
+  } else if (
+    (import.meta as unknown as ViteEnvVar)?.env?.VITE_INTLAYER_DEFAULT_LOCALE
+  ) {
+    // Likely Vite
+    return 'vite';
+  }
+
+  return 'unknown';
+};
+
+/**
+ * Get the prefix for the environment variables to be used in the platform
+ */
+export const getPrefix = (platform: Platform): string => {
+  switch (platform) {
+    case 'next':
+      return 'NEXT_PUBLIC_INTLAYER_';
+    case 'vite':
+      return 'VITE_INTLAYER_';
+    case 'react_app':
+      return 'REACT_APP_INTLAYER_';
+    default:
+      return '';
+  }
+};