diff --git a/packages/webpack5/src/helpers/config.ts b/packages/webpack5/src/helpers/config.ts index b194acf32..74b04ad35 100644 --- a/packages/webpack5/src/helpers/config.ts +++ b/packages/webpack5/src/helpers/config.ts @@ -11,6 +11,11 @@ function getCLILib() { return require(env.nativescriptLibPath); } +/** + * Utility to get a value from the nativescript.config.ts file. + * + * @param {string} key The key to get from the config. Supports dot-notation. + */ export function getValue(key: string): T { const lib = getCLILib(); diff --git a/packages/webpack5/src/helpers/copyRules.ts b/packages/webpack5/src/helpers/copyRules.ts index df0be51dc..c7e4b9195 100644 --- a/packages/webpack5/src/helpers/copyRules.ts +++ b/packages/webpack5/src/helpers/copyRules.ts @@ -7,10 +7,27 @@ import { getEntryDirPath } from './platform'; */ export let copyRules = new Set([]); +/** + * Utility to add new copy rules. Accepts a glob. For example + * - **\/*.html - copy all .html files found in any sub dir. + * - myFolder/* - copy all files from myFolder + * + * The path is relative to the folder of the entry file + * (specified in the main field of the package.json) + * + * @param {string} glob + */ export function addCopyRule(glob: string) { copyRules.add(glob); } +/** + * Utility to remove a copy rule. The glob should be the exact glob + * to remove. For example + * - fonts/** - to remove the default copy rule for fonts + * + * @param {string} glob + */ export function removeCopyRule(glob: string) { copyRules.delete(glob); } diff --git a/packages/webpack5/src/helpers/dependencies.ts b/packages/webpack5/src/helpers/dependencies.ts index c3c7dd470..37f22e8f3 100644 --- a/packages/webpack5/src/helpers/dependencies.ts +++ b/packages/webpack5/src/helpers/dependencies.ts @@ -2,6 +2,12 @@ import { getPackageJson, getProjectRootPath } from './project'; import path from 'path'; // todo: memoize +/** + * Utility to get all dependencies from the project package.json. + * The result combines dependencies and devDependencies + * + * @returns string[] dependencies + */ export function getAllDependencies(): string[] { const packageJSON = getPackageJson(); @@ -12,11 +18,23 @@ export function getAllDependencies(): string[] { } // todo: memoize +/** + * Utility to check if the project has a specific dependency + * in either dependencies or devDependencies. + * + * @param {string} dependencyName + * @returns boolean + */ export function hasDependency(dependencyName: string) { return getAllDependencies().includes(dependencyName); } // todo: memoize +/** + * Utility to get the path (usually nested in node_modules) of a dependency. + * + * @param dependencyName + */ export function getDependencyPath(dependencyName: string): string | null { try { const resolvedPath = require.resolve(`${dependencyName}/package.json`, { diff --git a/packages/webpack5/src/helpers/externalConfigs.ts b/packages/webpack5/src/helpers/externalConfigs.ts index ca0a9baff..518f8b97a 100644 --- a/packages/webpack5/src/helpers/externalConfigs.ts +++ b/packages/webpack5/src/helpers/externalConfigs.ts @@ -6,6 +6,9 @@ import { info, warn } from './log'; import * as lib from '../index'; import { clearCurrentPlugin, setCurrentPlugin } from '../index'; +/** + * @internal + */ export function applyExternalConfigs() { getAllDependencies().forEach((dependency) => { const packagePath = getDependencyPath(dependency); diff --git a/packages/webpack5/src/helpers/flavor.ts b/packages/webpack5/src/helpers/flavor.ts index 8a879dc2a..87b2bd8d5 100644 --- a/packages/webpack5/src/helpers/flavor.ts +++ b/packages/webpack5/src/helpers/flavor.ts @@ -2,6 +2,10 @@ import { defaultConfigs } from '@nativescript/webpack'; import { getAllDependencies } from './dependencies'; import { error } from './log'; +/** + * Utility to determine the project flavor based on installed dependencies + * (vue, angular, react, svelete, typescript, javascript...) + */ export function determineProjectFlavor(): keyof typeof defaultConfigs | false { const dependencies = getAllDependencies(); diff --git a/packages/webpack5/src/helpers/platform.ts b/packages/webpack5/src/helpers/platform.ts index 271d40b34..c8adde006 100644 --- a/packages/webpack5/src/helpers/platform.ts +++ b/packages/webpack5/src/helpers/platform.ts @@ -22,15 +22,27 @@ const platforms: { ios: iOSPlatform, }; +/** + * Utility to register a new supported platform. + * + * @param {string} name The name of the platform (eg. web, desktop) + * @param platform A platform definition of the platform specifics + */ export function addPlatform(name: string, platform: INativeScriptPlatform) { console.log('adding platform', name, platform); platforms[name] = platform; } +/** + * Utility to get the currently targeted platform definition + */ export function getPlatform(): INativeScriptPlatform { return platforms[getPlatformName()]; } +/** + * Utility to get the currently targeted platform name + */ export function getPlatformName(): Platform { if (env?.android) { return 'android'; @@ -62,6 +74,9 @@ export function getPlatformName(): Platform { `); } +/** + * Utility to get the entry file path for the currently targeted platform + */ export function getEntryPath() { const platform = getPlatform(); @@ -76,10 +91,16 @@ export function getEntryPath() { return resolve(getProjectRootPath(), packageJson.main); } +/** + * Utility to get the entry file directory path for the currently targeted platform + */ export function getEntryDirPath() { return dirname(getEntryPath()); } +/** + * Utility to get the dist file path for the currently targeted platform + */ export function getDistPath() { const platform = getPlatform(); @@ -92,6 +113,9 @@ export function getDistPath() { return `platforms/${getPlatformName()}/dist`; } +/** + * Utility to get the absolute dist file path for the currently targeted platform + */ export function getAbsoluteDistPath() { return resolve(getProjectRootPath(), getDistPath()); } diff --git a/packages/webpack5/src/helpers/project.ts b/packages/webpack5/src/helpers/project.ts index e2f5e1cd7..bdc874b0e 100644 --- a/packages/webpack5/src/helpers/project.ts +++ b/packages/webpack5/src/helpers/project.ts @@ -15,6 +15,9 @@ interface IPackageJson { // todo: add additional fields as we require them } +/** + * Utility function to get the contents of the project package.json + */ export function getPackageJson() { const packageJsonPath = resolve(getProjectRootPath(), 'package.json'); diff --git a/packages/webpack5/src/index.ts b/packages/webpack5/src/index.ts index d027d6308..e6d6e5e37 100644 --- a/packages/webpack5/src/index.ts +++ b/packages/webpack5/src/index.ts @@ -62,9 +62,22 @@ export function clearCurrentPlugin() { } ////// PUBLIC API +/** + * The default flavor specific configs + */ export const defaultConfigs = configs; + +/** + * Utilities to simplify various tasks + */ export const Utils = helpers; +/** + * Initialize @nativescript/webpack with the webpack env. + * Must be called first. + * + * @param _env The webpack env + */ export function init(_env: IWebpackEnv) { hasInitialized = true; if (_env) { @@ -72,6 +85,15 @@ export function init(_env: IWebpackEnv) { } } +/** + * Explicitly specify the base config to use. + * Calling this will opt-out from automatic flavor detection. + * + * Useful when the flavor cannot be detected due to the project structure + * for example in a custom monorepo. + * + * @param config Name of the base config to use. + */ export function useConfig(config: keyof typeof defaultConfigs | false) { explicitUseConfig = true; if (config) { @@ -82,6 +104,12 @@ export function useConfig(config: keyof typeof defaultConfigs | false) { } } +/** + * Add a new function to be called when building the internal config using webpack-chain. + * + * @param chainFn A function that accepts the internal chain config, and the current environment + * @param options Optional options to control the order in which the chain function should be applied. + */ export function chainWebpack( chainFn: (config: Config, env: IWebpackEnv) => any, options?: { order?: number } @@ -93,6 +121,11 @@ export function chainWebpack( }); } +/** + * Merge an object into the resolved chain config. + * + * @param mergeFn An object or a function that optionally returns an object (can mutate the object directly and return nothing) + */ export function mergeWebpack( mergeFn: ( config: Partial, @@ -102,6 +135,9 @@ export function mergeWebpack( webpackMerges.push(mergeFn); } +/** + * Resolve a new instance of the internal chain config with all chain functions applied. + */ export function resolveChainableConfig(): Config { const config = new Config(); @@ -144,6 +180,11 @@ export function resolveChainableConfig(): Config { return config; } +/** + * Resolve a "final" configuration that has all chain functions and merges applied. + * + * @param chainableConfig Optional chain config to use. + */ export function resolveConfig( chainableConfig = resolveChainableConfig() ): webpack.Configuration { diff --git a/packages/webpack5/src/plugins/PlatformSuffixPlugin.ts b/packages/webpack5/src/plugins/PlatformSuffixPlugin.ts index 4e0e186a6..b9e437ed4 100644 --- a/packages/webpack5/src/plugins/PlatformSuffixPlugin.ts +++ b/packages/webpack5/src/plugins/PlatformSuffixPlugin.ts @@ -8,6 +8,17 @@ interface PlatformSuffixPluginOptions { // extensions: string[] | (() => string[]) } +/** + * The platform suffix plugin will try to resolve files with a platform specifier (suffix) + * falling back to the non-platform-specific version. + * + * For example: + * import something from './something.js' + * + * will first look for './something..js' + * and if not found look for './something.js' + * + */ export class PlatformSuffixPlugin { private readonly platform: string; // private readonly extensions: string[] diff --git a/packages/webpack5/src/transformers/NativeClass/index.ts b/packages/webpack5/src/transformers/NativeClass/index.ts index 4d16ae658..71b832c1c 100644 --- a/packages/webpack5/src/transformers/NativeClass/index.ts +++ b/packages/webpack5/src/transformers/NativeClass/index.ts @@ -1,5 +1,10 @@ import ts from 'typescript'; +/** + * A TypeScript transform that compiles classes marked with @NativeClass as es5 & commonjs + * + * @param ctx + */ export default function (ctx: ts.TransformationContext) { function isNativeClassExtension(node: ts.ClassDeclaration) { return (