/home/techb158/trello-import.abdallabala.com
Edit: /home/techb158/trello-import.abdallabala.com/README.md (7149B)
# Trello Power-Up: Import JSON/CSV
A browser-only Trello Power-Up that imports cards from JSON or CSV into the current board.
## Features
- Board button: **Import JSON/CSV**
- CSV and JSON parsing in the browser
- Automatic field mapping with manual overrides
- Preview table before import
- Creates Trello cards through the Trello REST API
- Supports card name, description, list, due date, start date, labels, members, source URL, comments, and checklist items
- Optionally creates missing lists and labels
- Strict mode for safer imports
- Settings modal with authorization reset
- No backend and no external database
## Project structure
```text
public/
index.html Power-Up connector iframe
client.js Trello capability registration
import.html Import UI
settings.html Settings and authorization reset UI
onboarding.html Help screen shown on enable
js/config.js App key and app metadata
js/importer.js Parser, preview, mapping, REST import logic
js/settings.js Settings modal logic
css/styles.css UI styles
icons/ Board button and modal icons
samples/
cards.csv
cards.json
power-up.example.json Admin setup reference
package.json Local static server helper
```
## Trello admin setup
1. Go to Trello Power-Up Admin.
2. Create a new Power-Up.
3. Set the iframe connector URL to your HTTPS-hosted `public/index.html`, for example:
```text
https://your-domain.example/index.html
```
4. Enable these capabilities:
```text
board-buttons
on-enable
show-settings
```
5. Generate an API key in the Power-Up Admin **API Key** tab.
6. Add your hosted domain to the allowed origins in the same API Key tab.
7. Edit `public/js/config.js`:
```js
window.TRELLO_IMPORT_CONFIG = {
appKey: "YOUR_TRELLO_POWERUP_API_KEY",
appName: "Import JSON/CSV",
appAuthor: "Your Name or Company",
appVersion: "1.0.0"
};
```
The API key is intended to be public. User tokens are private and are stored by Trello’s Power-Up REST client after user consent.
## VPS deployment with Cloudflare Tunnel
Use this option when you do not want to open inbound `80` or `443` on the VPS, the server is behind NAT or a firewall, or you want outbound-only traffic to Cloudflare.
This bundle includes:
```text
docker-compose.cloudflare.yml
deploy/CLOUDFLARE_TUNNEL.md
```
The Cloudflare Tunnel deployment keeps the app private inside Docker and exposes only the Cloudflare hostname, for example:
```text
https://trello-import.example.com/index.html
```
Start with:
```bash
cp .env.example .env
# edit .env and set TRELLO_APP_KEY plus CLOUDFLARE_TUNNEL_TOKEN
docker compose -f docker-compose.cloudflare.yml up -d --build
```
In Cloudflare Tunnel public hostname settings, route the hostname to:
```text
http://trello-import-powerup:80
```
See `deploy/CLOUDFLARE_TUNNEL.md` for the full checklist.
## VPS deployment with Docker and Nginx
This bundle now includes VPS deployment files:
```text
Dockerfile
docker-compose.yml
.env.example
docker/
nginx.conf
render-config.sh
deploy/
nginx-site.conf
VPS_DEPLOYMENT.md
```
Recommended VPS layout:
1. Run the static Power-Up in Docker on `127.0.0.1:8080`.
2. Use host Nginx or another reverse proxy for HTTPS.
3. Point Trello Power-Up Admin to `https://your-domain.example/index.html`.
4. Add `https://your-domain.example` as an allowed origin in the Power-Up API Key tab.
Start locally on the VPS:
```bash
cp .env.example .env
# edit .env and set TRELLO_APP_KEY
docker compose up -d --build
```
See `deploy/VPS_DEPLOYMENT.md` for the full VPS checklist.
## Deployment
This is a static site. Deploy the contents of `public/` to any HTTPS host.
Good options:
- GitHub Pages
- Netlify
- Cloudflare Pages
- Vercel static hosting
- S3 plus CloudFront
For local development:
```bash
npm install
npm run serve
```
Trello requires an HTTPS connector, so expose the local server with a secure tunnel, then use that tunnel URL in Trello Power-Up Admin.
Examples:
```bash
ngrok http 8080
```
or
```bash
cloudflared tunnel --url http://localhost:8080
```
## Accepted CSV columns
The importer auto-detects common aliases. You can override mappings in the UI.
| Trello field | Common CSV or JSON keys |
| --- | --- |
| Card name | `name`, `title`, `card`, `summary`, `task`, `subject` |
| Description | `desc`, `description`, `details`, `body`, `notes` |
| List | `list`, `list name`, `status`, `stage`, `lane`, `column` |
| Due date | `due`, `due date`, `duedate`, `deadline` |
| Start date | `start`, `start date`, `startdate` |
| Labels | `labels`, `label`, `tags`, `tag` |
| Members | `members`, `member`, `assignees`, `assignee`, `assigned to`, `owners` |
| Checklist | `checklist`, `checklists`, `check items`, `todo`, `subtasks` |
| Comments | `comments`, `comment`, `activity` |
| Source URL | `url`, `source`, `source url`, `link`, `attachment url` |
| Position | `position`, `pos` |
Multiple labels, members, comments, or checklist items can be separated with semicolons, pipes, or new lines.
## CSV example
```csv
name,list,desc,due,labels,members,checklist
Write launch brief,To Do,Prepare first draft,2026-07-10,Marketing;Priority,alice,Outline|Draft|Review
QA importer,In Progress,Test CSV and JSON cases,2026-07-12,Engineering,bob,Parse CSV|Preview rows|Import cards
```
## JSON example
```json
{
"cards": [
{
"name": "Plan kickoff",
"list": "To Do",
"desc": "Schedule the kickoff and prepare agenda.",
"due": "2026-07-14",
"labels": ["Planning", "Priority"],
"members": ["alice"],
"checklist": ["Draft agenda", "Invite team", "Share notes"]
}
]
}
```
The root JSON may be an array, or an object containing a `cards`, `items`, or `data` array.
## Import behavior
- The current board ID is read from the Power-Up iframe context.
- Existing open lists are loaded from the board.
- Existing labels and board members are loaded before preview.
- Missing lists can be created automatically.
- Missing labels can be created automatically with no color.
- Members are matched by username, full name, or Trello member ID.
- Unmatched members are skipped unless strict mode is enabled.
- Cards are created sequentially with a configurable delay to reduce API pressure.
- File contents are not uploaded to this Power-Up project or stored remotely.
## Important limitations
- This version creates new cards only. It does not update existing cards.
- This version does not import Trello custom fields.
- It does not create Trello accounts or invite users. Members must already belong to the board to be assigned.
- Attachments from local files are not uploaded. A `urlSource` column can attach a valid HTTP or HTTPS source URL during card creation.
- Power-Ups run inside Trello while the user is present. This importer does not run scheduled or background imports.
## Verification
Run a syntax check:
```bash
npm run check
```
Then test in Trello using a development board and the sample files in `samples/`.
## License
MIT