@intlayer/config 1.0.2 → 1.2.1

package/src/configFile/buildConfigurationFields.ts

@@ -9,16 +9,16 @@ 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,
+  I18N_DICTIONARIES_DIR_NAME,
+  DICTIONARY_OUTPUT,
 } from '../defaultValues/server';
 import type {
   BaseDerivedConfig,
@@ -35,17 +35,24 @@ 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 +60,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,87 +123,289 @@ 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.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
+     *
+     * - 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 will be stored
+     *
+     * Default: 'dictionary'
+     *
+     * Example: 'translations'
+     *
+     * Note:
+     * - If this directory is not at the result directory level, update the dictionariesDir field instead
+     *
+     */
+    i18nDictionariesDirName:
+      customConfiguration?.i18nDictionariesDirName ??
+      I18N_DICTIONARIES_DIR_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
     ),
+
+    /**
+     * Output format of the dictionary
+     *
+     * Default: ['intlayer']
+     *
+     * Note:
+     * - 'i18next' is not yet ensure a 1:1 mapping with the i18next library.
+     * - Removing 'intlayer' will break the compatibility with react-intlayer or next-intlayer
+     */
+    dictionaryOutput:
+      customConfiguration?.dictionaryOutput ?? DICTIONARY_OUTPUT,
   };
 
   const resultDirDerivedConfiguration: ResultDirDerivedConfig = {
-    // Directory where the bundle will be stored
-    bundleDir: join(
+    /**
+     * 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.bundleDirName
+      notDerivedContentConfig.dictionariesDirName
     ),
 
-    // Directory where the dictionaries will be stored
-    dictionariesDir: join(
+    /**
+     * Directory where the 18n dictionaries will be stored
+     *
+     * Relative to the result directory
+     *
+     * Default: {{resultDir}} / {{i18nDictionariesDirName}}
+     *
+     * Example: '/path/to/project/.intlayer/dictionary/i18n'
+     *
+     * Note:
+     * - If the types are not at the result directory level, update the i18nDictionariesDirName field instead
+     */
+    i18nDictionariesDir: join(
       baseDirDerivedConfiguration.resultDir,
-      notDerivedContentConfig.dictionariesDirName
+      notDerivedContentConfig.i18nDictionariesDirName
     ),
 
-    // 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 +413,29 @@ const buildContentFields = (
   };
 
   const patternsConfiguration: PatternsContentConfig = {
-    // Pattern of files to watch
+    /**
+     * Pattern of files to watch
+     *
+     * Default: ['/**\/*.content.ts', '/**\/*.content.js', '/**\/*.content.json', '/**\/*.content.cjs', '/**\/*.content.mjs', '/**\/*.content.tsx', '/**\/*.content.jsx']
+     */
     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', '{{contentDir}}/**\/*.content.cjs', '{{contentDir}}/**\/*.content.mjs', '{{contentDir}}/**\/*.content.tsx', '{{contentDir}}/**\/*.content.jsx']
+     */
     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 +447,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

@@ -1,4 +1,14 @@
-export const FILE_EXTENSIONS = ['.content.ts', '.content.js', '.content.json'];
+import type { DictionaryOutput } from '../types/config';
+
+export const FILE_EXTENSIONS = [
+  '.content.ts',
+  '.content.js',
+  '.content.cjs',
+  '.content.mjs',
+  '.content.json',
+  '.content.tsx',
+  '.content.jsx',
+];
 export const EXCLUDED_PATHS = ['node_modules'];
 
 export const CONTENT_DIR_NAME = 'src';
@@ -7,12 +17,12 @@ 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 DICTIONARY_OUTPUT: DictionaryOutput[] = ['intlayer'];
 
 export const DICTIONARIES_DIR_NAME = 'dictionary';
 
+export const I18N_DICTIONARIES_DIR_NAME = 'i18n_dictionary';
+
 export const TYPES_DIR_NAME = 'types';
 
 export const MAIN_DIR_NAME = 'main';

package/src/envVariables/detectPlatform.ts

@@ -0,0 +1,41 @@
+export type Platform = 'next' | 'vite' | 'react_app' | 'unknown';
+
+export const getPlatform = (): Platform => {
+  if (
+    // eslint-disable-next-line
+    typeof import.meta !== 'undefined' &&
+    typeof import.meta.env !== 'undefined' &&
+    typeof import.meta.env.VITE_INTLAYER_DEFAULT_LOCALE !== 'undefined'
+  ) {
+    // Likely Vite
+    return 'vite';
+  } else if (
+    typeof process.env.NEXT_PUBLIC_INTLAYER_DEFAULT_LOCALE !== 'undefined'
+  ) {
+    // Likely Next.js
+    return 'next';
+  } else if (
+    typeof process.env.REACT_APP_INTLAYER_DEFAULT_LOCALE !== 'undefined'
+  ) {
+    // Likely Create React App
+    return 'react_app';
+  }
+
+  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 '';
+  }
+};

package/src/envVariables/extractEnvVariable/index.ts

@@ -0,0 +1,20 @@
+import { type Platform, getPlatform } from '../detectPlatform';
+import { extractNextEnvVariable } from './next';
+import { extractReactAppEnvVariable } from './react_app';
+import type { IntlayerConfigEnvVariable } from './types';
+import { extractEmptyEnvVariable } from './undefined_platform';
+import { extractViteEnvVariable } from './vite';
+
+export const extractEnvVariable = (): IntlayerConfigEnvVariable => {
+  const platform: Platform = getPlatform();
+
+  if (platform === 'vite') {
+    return extractViteEnvVariable();
+  } else if (platform === 'next') {
+    return extractNextEnvVariable();
+  } else if (platform === 'react_app') {
+    return extractReactAppEnvVariable();
+  }
+
+  return extractEmptyEnvVariable();
+};