Comprehensive utility functions for package management, validation, git operations, file handling, and network connectivity used throughout the project creation process.
Automatic detection of the user's preferred package manager based on the environment.
/**
* Detect the user's preferred package manager from environment
* @returns Detected package manager type
*/
function getPkgManager(): PackageManager;
type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';Detection Logic:
npm_config_user_agent environment variableUsage Examples:
The getPkgManager function is used internally by the CLI tool to detect the user's package manager preference automatically during project creation.
Validation of npm package names according to npm naming conventions.
/**
* Validate npm package name according to npm rules
* @param name - Package name to validate
* @returns Validation result with problems if invalid
*/
function validateNpmName(name: string): ValidateNpmNameResult;
type ValidateNpmNameResult =
| { valid: true }
| { valid: false; problems: string[] };Usage Examples:
The validateNpmName function is used internally to validate project names entered by users, ensuring they follow npm package naming conventions.
Check if a directory is empty or contains only allowed development files.
/**
* Check if folder is empty or contains only allowed files
* @param root - Directory path to check
* @param name - Project name for error messages
* @returns True if folder is suitable for project creation
*/
function isFolderEmpty(root: string, name: string): boolean;Allowed Files:
.DS_Store, .git, .gitattributes, .gitignore.gitlab-ci.yml, .hg, .hgcheck, .hgignore.idea, .npmignore, .travis.ymlLICENSE, Thumbs.db, docs, mkdocs.ymlnpm-debug.log, yarn-debug.log, yarn-error.logyarnrc.yml, .yarn.iml extension)Usage Examples:
The isFolderEmpty function is used internally to ensure the target directory is suitable for project creation, checking for conflicting files before proceeding.
Git repository initialization with comprehensive error handling and branch setup.
/**
* Initialize git repository with error handling
* @param root - Project root directory
* @returns True if git initialization succeeded
*/
function tryGitInit(root: string): boolean;Git Operations:
Usage Examples:
The tryGitInit function is used internally to initialize git repositories for new projects, with automatic fallback when git is unavailable.
Package installation with support for different package managers and offline mode.
/**
* Install packages using specified package manager
* @param packageManager - Package manager to use
* @param isOnline - Whether internet connection is available
*/
async function install(
packageManager: PackageManager,
isOnline: boolean
): Promise<void>;Features:
Usage Examples:
The install function is used internally to install project dependencies using the user's preferred package manager.
Internet connectivity detection with proxy support for package manager operations.
/**
* Check internet connectivity including proxy support
* @returns True if online connectivity is available
*/
async function getOnline(): Promise<boolean>;Detection Method:
registry.yarnpkg.comUsage Examples:
The getOnline function is used internally to detect internet connectivity and automatically configure package managers for offline mode when necessary.
Directory writability checking and file copying with glob pattern support.
/**
* Check if directory is writable
* @param directory - Directory path to check
* @returns True if directory is writable
*/
async function isWriteable(directory: string): Promise<boolean>;
/**
* Copy files with glob patterns and transformations
* @param src - Source files or glob patterns
* @param dest - Destination directory
* @param options - Copy configuration options
*/
async function copy(
src: string | string[],
dest: string,
options?: CopyOption
): Promise<void>;
interface CopyOption {
/** Working directory for source patterns */
cwd?: string;
/** Function to rename files during copy */
rename?: (basename: string) => string;
/** Whether to preserve directory structure */
parents?: boolean;
}Usage Examples:
The isWriteable and copy functions are used internally for directory validation and template file copying during project creation.
Functions for handling GitHub repositories and Next.js examples during project creation.
/**
* Parse GitHub repository information from URL
* @param url - GitHub repository URL
* @param examplePath - Optional path within repository
* @returns Repository information or undefined if invalid
*/
async function getRepoInfo(
url: URL,
examplePath?: string
): Promise<RepoInfo | undefined>;
/**
* Check if repository exists and has package.json
* @param repoInfo - Repository information
* @returns True if repository is accessible
*/
function hasRepo(repoInfo: RepoInfo): Promise<boolean>;
/**
* Check if Next.js example exists
* @param nameOrUrl - Example name or GitHub URL
* @returns True if example exists
*/
function existsInRepo(nameOrUrl: string): Promise<boolean>;
/**
* Download and extract GitHub repository
* @param root - Target directory
* @param repoInfo - Repository information
*/
async function downloadAndExtractRepo(
root: string,
repoInfo: RepoInfo
): Promise<void>;
/**
* Download and extract Next.js example
* @param root - Target directory
* @param name - Example name
*/
async function downloadAndExtractExample(
root: string,
name: string
): Promise<void>;
interface RepoInfo {
username: string;
name: string;
branch: string;
filePath: string;
}Usage Examples:
These functions are used internally to handle example downloading from GitHub repositories and the official Next.js examples repository.