triston-notes/Cards/dev/NPM package structure.md
2023-10-21 18:52:54 -05:00

290 lines
7.2 KiB
Markdown

up:: [[Boilerplate Code]]
X:: [[JavaScript]]
tags:: #boilerplate
# NPM Package Structure
## <span style='color: #337ea9'>File Structure for NPM module template</span>
Use this as a guide to creating a basic npm module that actual works and will deploy from Github to npmjs.org
First install TypeScript
```bash
npm i -d typescript
```
Then initialize typescript
```bash
npx tsc --init
```
---
### Add CI/CD configs in github folder
- .github
- funding.yml
```yaml
# These are supported funding model platforms
github: [] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: # Replace with a single Open Collective username
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
```
- workflows
- release.yml
```jsx
name: CI & npm publish
on:
push:
branches: [main]
paths-ingore:
- 'package.json'
jobs:
bump_version:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}
- run: git config --global user.name 'Triston Armstrong'
- run: git config --global user.email 'triston95strong@gmail.com'
- run: npm version patch -m "chore(release) %s"
- run: git push
build:
needs: bump_version
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 'lts/*'
registry-url: 'https://registry.npmjs.org'
- run: npm ci
pre_release:
needs: build
runs-on: ubuntu-latest
steps:
- name: Create Github Release
uses: 'marvinpinto/action-automatic-releases@latest'
with:
repo_token: '${{ secrets.GITHUB_TOKEN }}'
automatic_release_tag: 'latest'
prerelease: false
publish:
needs: pre_release
runs-on: ubuntu-latest
permissions:
packages: write
contents: read
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 12
registry-url: 'https://registry.npmjs.org'
- name: Getting Dependencies
run: npm ci
- name: Publishing to NPM
run: npm publish
env:
NODE_AUTH_TOKEN: ${{secrets.NPM_RELEASE_DEP}}
```
- pr-check.yml
```jsx
name: Validate PR
on:
pull_request:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 'lts/*'
registry-url: 'https://registry.npmjs.org'
- run: npm ci
- run: npm run fix
- run: npm run build
```
---
### Lib folder contains generated files
- lib
this is where the build scripts will go - nothing to do here
---
### Src folder contains all project files
- src
All project build files go here including index file
- examples
---
### We want to ignore the lib folder
- .gitignore
add /lib folder to gitignore - thats it aside from the default generated ignore
---
### Various configuration files
- .npmrc
```jsx
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@tarmstrong95:registry=https://npm.pkg.github.com
always-auth=true
```
- .prettierignore
```jsx
node_modules
yarn.lock
lib
dist
```
- .prettierrc.json
```jsx
{
"singleQuote": true,
"semi": false,
"trailingComma": "none",
"arrowParens": "avoid"
}
```
- .tslintignore
```jsx
node_modules
yarn.lock
lib
dist
```
---
### Template files
- package.json
a few changes needed on this one
```jsx
{
"name": "project name",
"version": "1.0.0",
"description": "project description",
"main": "lib/index.js",
"author": "Triston Armstrong",
"license": "MIT",
"types": "lib/index.d.ts",
"scripts": {
"start": "tsc --watch",
"prepublishOnly": "npm run fix",
"publish": "npm run build",
"build": "npm run clean && tsc",
"fix": "npm run lint; npm run format",
"clean": "tsc --build --clean",
"format": "prettier --write \"src/**/*.ts\"",
"lint": "tslint -p tsconfig.json"
},
"dependencies": {
// install dependencies
},
"devDependencies": {
// install dev dependencies
},
"peerDependencies": {
// install any peer dependencies
},
"keywords": [
// keywords for this project
],
"files": [
"lib/**/*"
],
"repository": {
"type": "git",
"url": "git+https://github.com/Tarmstrong95/REPO NAME.git"
},
"bugs": {
"url": "https://github.com/Tarmstrong95/REPO NAME/issues"
},
"homepage": "https://github.com/Tarmstrong95/REPO NAME#readme",
"publishConfig": {
"registry": "https://registry.npmjs.org"
}
}
```
- README.md
copy readme structure from other projects
- tsconfig.json
no changes needed to this one
```jsx
{
"compilerOptions": {
"jsx": "react",
"target": "ES2015",
"module": "commonjs",
"declaration": true,
"outDir": "./lib",
"strict": true
},
"include": ["src"],
"exclude": [
"node_modules",
"**/__tests__/*",
"src/examples/*",
"src/setupTests.ts"
]
}
```
- tslint.json