|
| 1 | +--- |
| 2 | +title: Frontend Dependencies |
| 3 | +description: Learn how package.json works and how to manage frontend dependencies in UserFrosting. |
| 4 | +--- |
| 5 | + |
| 6 | +## Understanding Package.json |
| 7 | + |
| 8 | +The `package.json` file is the heart of any Node.js project, including UserFrosting's frontend asset management. Think of it as the instruction manual and blueprint for your project—it tells NPM (Node Package Manager) what your project needs, how to build it, and how to run various tasks. |
| 9 | + |
| 10 | +> [!TIP] |
| 11 | +> The `package.json` file is to JavaScript projects what `composer.json` is to PHP projects—it manages external dependencies and defines how to work with your project. |
| 12 | +
|
| 13 | +### What is Package.json? |
| 14 | + |
| 15 | +According to the [official NPM documentation](https://docs.npmjs.com/cli/v10/configuring-npm/package-json), `package.json` is a JSON file that serves multiple critical purposes: |
| 16 | + |
| 17 | +1. **Dependency Management** - Lists all external packages (libraries) your project needs |
| 18 | +2. **Project Metadata** - Defines your project's name, version, description, and author |
| 19 | +3. **Script Automation** - Contains commands for building, testing, and running your application |
| 20 | +4. **Version Control** - Specifies exact or acceptable versions of each dependency |
| 21 | +5. **Configuration** - Stores settings for various tools and build processes |
| 22 | + |
| 23 | +### Package.json and NPM |
| 24 | + |
| 25 | +[NPM (Node Package Manager)](https://www.npmjs.com/) is the default package manager for Node.js and the world's largest software registry. When you install NPM packages, the registry at [npmjs.com](https://www.npmjs.com/) hosts millions of open-source packages that developers can use in their projects. |
| 26 | + |
| 27 | +Here's how `package.json` and NPM work together: |
| 28 | + |
| 29 | +1. **Installation** - When you run `npm install`, NPM reads `package.json` to determine which packages to download |
| 30 | +2. **Version Resolution** - NPM checks the version constraints (like `^3.4.0`) and installs compatible versions |
| 31 | +3. **Dependency Tree** - NPM automatically installs each package's dependencies, creating a `node_modules` folder |
| 32 | +4. **Lock File** - NPM generates `package-lock.json` to ensure everyone installs identical versions |
| 33 | + |
| 34 | +> [!NOTE] |
| 35 | +> The `package-lock.json` file is automatically generated and should be committed to version control. It locks exact versions of all dependencies, ensuring consistent installations across different environments. [Learn more about package-lock.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json). |
| 36 | +
|
| 37 | +### UserFrosting's Package.json |
| 38 | + |
| 39 | +UserFrosting's [Skeleton template](https://github.com/userfrosting/UserFrosting) includes a pre-configured `package.json` with everything you need to get started. You don't need to create this file from scratch—it's already set up with sensible defaults for Vite, Vue 3, TypeScript, and all necessary build tools. |
| 40 | + |
| 41 | +**However, you can and should customize it to fit your project's needs:** |
| 42 | + |
| 43 | +- **Add new dependencies** for features you need (e.g., date pickers, charts, UI components) |
| 44 | +- **Remove unused dependencies** to reduce bundle size |
| 45 | +- **Update versions** to get bug fixes and new features |
| 46 | +- **Add custom scripts** for your specific workflows |
| 47 | +- **Modify existing scripts** to change build behavior |
| 48 | + |
| 49 | +For example, if your project needs a date picker library, you would add it: |
| 50 | + |
| 51 | +```bash |
| 52 | +npm install --save flatpickr |
| 53 | +``` |
| 54 | + |
| 55 | +This automatically updates your `package.json` with the new dependency: |
| 56 | + |
| 57 | +```json |
| 58 | +{ |
| 59 | + "dependencies": { |
| 60 | + "flatpickr": "^4.6.13" |
| 61 | + } |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +### Package.json Structure |
| 66 | + |
| 67 | +Your `package.json` includes several key sections. Let's break down a typical UserFrosting configuration: |
| 68 | + |
| 69 | +```json |
| 70 | +{ |
| 71 | + "name": "userfrosting-app", |
| 72 | + "version": "1.0.0", |
| 73 | + "type": "module", |
| 74 | + "scripts": { |
| 75 | + ... |
| 76 | + }, |
| 77 | + "dependencies": { |
| 78 | + ... |
| 79 | + }, |
| 80 | + "devDependencies": { |
| 81 | + ... |
| 82 | + } |
| 83 | +} |
| 84 | +``` |
| 85 | + |
| 86 | +#### Project Metadata |
| 87 | + |
| 88 | +- **`name`** - Your project's identifier (used for publishing to NPM if public) |
| 89 | +- **`version`** - Current version following [SemVer](https://semver.org/) format (MAJOR.MINOR.PATCH) |
| 90 | +- **`type`** - Set to `"module"` to enable ES modules (import/export syntax) |
| 91 | + |
| 92 | +#### Dependencies vs DevDependencies |
| 93 | + |
| 94 | +Understanding the difference between these two sections is important: |
| 95 | + |
| 96 | +**`dependencies`** - Packages required for your application to run in production. In other words, they are necessary to run the code in the browser. These are installed in all environments and included in your final build. Examples of dependencies include: |
| 97 | +- **`vue`** - The Vue.js framework for building user interfaces |
| 98 | +- **`vue-router`** - Official router for Vue.js applications |
| 99 | +- **`axios`** - Promise-based HTTP client for making API requests |
| 100 | + |
| 101 | +**`devDependencies`** - Packages only needed during development and building. These are not included in production bundles. In other words, they are tools you use to build your assets, used in the command line or in your code IDE. Examples of devDependencies includes: |
| 102 | +- **`vite`** - The build tool itself |
| 103 | +- **`typescript`** - TypeScript compiler for type-safe JavaScript |
| 104 | +- **`vitest`** - Fast unit testing framework powered by Vite |
| 105 | +- **`eslint`** - JavaScript/TypeScript linter for code quality |
| 106 | + |
| 107 | +> [!TIP] |
| 108 | +> When installing new packages, use `npm install --save` (for dependencies) or `npm install --save-dev` (for devDependencies). The `--save` flag is now default in modern NPM versions, so `npm install package-name` adds to dependencies. |
0 commit comments