0
# Publishing
1

2
Publishing packages to npm registry with coordinated releases and access verification.
3

4
## Capabilities
5

6
### Publish Command
7

8
Publishes packages to npm registry with automatic version management and access verification.
9

10
```bash { .api }
11
# Publish changed packages (runs version first)
12
lerna publish
13

14
# Publish from current git tag (skip versioning)
15
lerna publish from-git
16

17
# Publish packages marked as needing publication
18
lerna publish from-package
19

20
# Publish specific version
21
lerna publish 1.2.3
22
lerna publish patch
23
lerna publish minor
24
lerna publish major
25
lerna publish prerelease
26

27
# Publish with specific npm tag
28
lerna publish --dist-tag next
29
lerna publish --dist-tag beta
30

31
# Publish with custom registry
32
lerna publish --registry https://custom-registry.com
33

34
# Skip npm publish (git operations only)
35
lerna publish --skip-npm
36

37
# Skip git operations
38
lerna publish --skip-git
39

40
# Force publish all packages
41
lerna publish --force-publish
42

43
# Confirm all prompts automatically
44
lerna publish --yes
45

46
# Custom OTP (One-Time Password) for 2FA
47
lerna publish --otp 123456
48

49
# Publish pre-built packages
50
lerna publish from-package --contents dist
51
```
52

53
### Publishing Workflow
54

55
The `lerna publish` command performs:
56

57
1. **Version Management**: Runs `lerna version` if not using `from-git` or `from-package`
58
2. **Build Verification**: Ensures packages are built and ready for publishing
59
3. **Access Verification**: Checks npm registry access and 2FA requirements
60
4. **License Verification**: Validates package licenses exist
61
5. **Package Publishing**: Publishes to npm registry in topological order
62
6. **Tag Management**: Updates npm dist-tags appropriately
63

64
### Publishing Modes
65

66
#### Standard Publishing
67
```bash { .api }
68
# Version and publish changed packages
69
lerna publish
70

71
# Equivalent to:
72
# lerna version + lerna publish from-git
73
```
74

75
#### From Git Tag
76
```bash { .api }
77
# Publish packages based on current git tag
78
lerna publish from-git
79

80
# Useful in CI after lerna version has been run
81
```
82

83
#### From Package
84
```bash { .api }
85
# Publish packages where version > registry version
86
lerna publish from-package
87

88
# Useful for recovering from failed publishes
89
```
90

91
## Publishing Configuration
92

93
```typescript { .api }
94
interface PublishConfig {
95
  /** npm registry URL */
96
  registry?: string;
97
  /** Package access level */
98
  access?: 'public' | 'restricted';
99
  /** Commit message for publish */
100
  message?: string;
101
  /** Use conventional commits */
102
  conventionalCommits?: boolean;
103
  /** Skip confirmation prompts */
104
  yes?: boolean;
105
  /** npm dist-tag for published packages */
106
  distTag?: string;
107
  /** Skip npm publish (git only) */
108
  skipNpm?: boolean;
109
  /** Skip git operations */
110
  skipGit?: boolean;
111
  /** Directory to publish (relative to package root) */
112
  contents?: string;
113
  /** Force publish all packages */
114
  forcePublish?: boolean | string | string[];
115
  /** One-time password for 2FA */
116
  otp?: string;
117
  /** Verify package access before publishing */
118
  verifyAccess?: boolean;
119
  /** Create temporary license files */
120
  createRelease?: 'github' | 'gitlab';
121
  /** Pre/post publish lifecycle scripts */
122
  prePublishOnly?: string;
123
  postPublishOnly?: string;
124
}
125
```
126

127
**Usage in lerna.json:**
128

129
```json
130
{
131
  "command": {
132
    "publish": {
133
      "registry": "https://registry.npmjs.org",
134
      "access": "public",
135
      "conventionalCommits": true,
136
      "message": "chore: publish",
137
      "distTag": "latest",
138
      "verifyAccess": true
139
    }
140
  }
141
}
142
```
143

144
**Package-specific configuration in package.json:**
145

146
```json
147
{
148
  "publishConfig": {
149
    "registry": "https://custom-registry.com",
150
    "access": "public",
151
    "tag": "next"
152
  }
153
}
154
```
155

156
## Access Management
157

158
### npm Access Verification
159

160
Lerna verifies npm registry access before publishing:
161

162
```bash { .api }
163
# Verify access for all packages
164
lerna publish --verify-access
165

166
# Skip access verification  
167
lerna publish --no-verify-access
168
```
169

170
Access verification checks:
171
- User authentication with registry
172
- Package publication permissions
173
- Organization membership (for scoped packages)
174
- Two-factor authentication requirements
175

176
### Two-Factor Authentication
177

178
```bash { .api }
179
# Provide OTP for 2FA-enabled accounts
180
lerna publish --otp 123456
181

182
# Lerna will prompt for OTP if required and not provided
183
lerna publish
184
# ? Please enter a one-time password: [input]
185
```
186

187
## Registry Configuration
188

189
### Custom Registry
190

191
```bash { .api }
192
# Publish to custom registry
193
lerna publish --registry https://custom-registry.com
194

195
# Use registry from .npmrc
196
lerna publish
197
```
198

199
### Multiple Registries
200

201
Configure different registries per package scope in `.npmrc`:
202

203
```ini
204
@myorg:registry=https://custom-registry.com
205
@public:registry=https://registry.npmjs.org
206
```
207

208
## Package Contents
209

210
### Custom Contents Directory
211

212
```bash { .api }
213
# Publish from dist directory
214
lerna publish --contents dist
215

216
# Publish from build directory
217
lerna publish from-package --contents build
218
```
219

220
This publishes the contents of the specified directory as the package root, useful for:
221
- Compiled TypeScript packages
222
- Bundled packages  
223
- Packages with build steps
224

225
### File Inclusion
226

227
Control published files via package.json:
228

229
```json
230
{
231
  "files": [
232
    "dist",
233
    "lib",
234
    "!**/*.test.js"
235
  ]
236
}
237
```
238

239
## Error Handling
240

241
### Failed Publishes
242

243
```bash { .api }
244
# Recover from failed publish
245
lerna publish from-package
246

247
# Force republish specific packages
248
lerna publish from-package --force-publish package-name
249

250
# Skip packages that failed to publish
251
lerna publish from-git --no-verify-access
252
```
253

254
### Lifecycle Scripts
255

256
Lerna respects npm lifecycle scripts:
257

258
- `prepublishOnly` - Run before publishing (npm 5+)
259
- `prepack` - Run before tarball creation
260
- `postpack` - Run after tarball creation  
261
- `postpublish` - Run after successful publish
262

263
```json
264
{
265
  "scripts": {
266
    "prepublishOnly": "npm run build",
267
    "postpublish": "echo 'Published successfully!'"
268
  }
269
}
270
```