Ingest dependencies from a package.json file and relate them to a service

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

Open in ClaudeOpen in CodexOpen in Cursor

Open plan mode. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/ingest-dependencies-from-package-json-to-service

Goal: get the guide's core flow working end-to-end in my org; adapting it to fit my existing setup takes priority over matching the guide 1:1.

Plan:
1. Confirm MCP is connected, in the right org, with sufficient permissions.
2. Diff the guide's data model (blueprints, properties, relations, actions, agents, automations, integrations, secrets) against mine.
3. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
4. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out.
5. Stop on any blocker and give me options. Approving this plan authorizes the writes it lists; pause only for writes beyond what's listed.

Build:
- Extend blueprint schema additively when upserting; don't remove or overwrite existing properties, and treat type conflicts as a blocker, not an auto-fix.
- List any mock data in the plan, minimal and labeled mock; once approved, seed it without re-asking, and tell me what you seeded.
- For anything the guide writes downstream (e.g. a webhook target), use a real entity, not a mock.
- For pages/widgets, use the real page identifier from the app URL, not a guessed slug.
- When you hit a UI step confirmed (not assumed) unsupported via MCP, pause, give exact clicks, then resume via MCP.
- Validate and give links after each meaningful step (only a tool-returned URL, no guessed paths); don't proceed if the last run wasn't a success.

Done:
- Confirm the guide's expected output exists and runs in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

Overview

This guide will demonstrate how to ingest dependencies from a package.json file and relate them to the corresponding service entities in Port.

Prerequisites

• This guide assumes you have a Port account and that you have finished the onboarding process.

• Install GitHub Ocean.

Set up data model

Add a dependency blueprint

1. Go to the Builder in your Port portal.

2. Click on "+ Blueprint".

3. Click on the {...} button in the top right corner, and choose "Edit JSON"

4. Add this JSON schema:

   Dependency blueprint (click to expand)

   {
     "identifier": "dependency",
     "title": "Dependency",
     "icon": "Package",
     "schema": {
       "properties": {
         "package_name": {
           "icon": "DefaultProperty",
           "type": "string",
           "title": "Package name"
         },
         "semver_requirement": {
           "type": "string",
           "title": "Semver requirement"
         },
         "type": {
           "type": "string",
           "title": "Type",
           "enum": [
             "Production",
             "Development"
           ]
         },
         "url": {
           "type": "string",
           "title": "URL",
           "format": "url"
         }
       },
       "required": [
         "package_name",
         "semver_requirement"
       ]
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {}
   }
   

Ingest dependencies from package.json

To ingest dependencies listed in package.json files, follow these steps:

1. Go to the data sources page in your Port portal, and select your GitHub integration.

2. Modify the mapping to include the file kind with the configuration provided below:

   Port configuration (click to expand)

     - kind: file
       selector:
         query: 'true'
         files:
           - path: '**/package.json'
             organization: my-org  # Optional if githubOrganization is set (required if not set)
             repos:
               - name: MyRepo
                 branch: main
       port:
         itemsToParse: .content.dependencies | to_entries
         entity:
           mappings:
             identifier: >-
               .item.key + "_" +  (.item.value |  gsub("\\^"; "caret_") |
               gsub("~"; "tilde_") |  gsub(">="; "gte_") |  gsub("<="; "lte_") |
               gsub(">"; "gt_") |  gsub("<"; "lt_") |  gsub("@"; "at_") |
               gsub("\\*"; "star") |  gsub(" "; "_"))
             title: .item.key + "@" + .item.value
             blueprint: '"dependency"'
             properties:
               package_name: .item.key
               semver_requirement: .item.value

   Configuration details

   • kind: file specifies that the source is a file, in this case, package.json.

   • files: defines the path pattern to locate package.json files within your repositories.

   • itemsToParse: identifies the specific array within the package.json (i.e., dependencies) that you want to parse into individual dependency entities. For GitHub Ocean, use .content instead of .file.content.

   • identifier: constructs a unique identifier for each dependency, accounting for special characters in the version string.

   • properties: captures essential details like the package name and version.

Relate the dependencies to the service

Once the dependencies have been ingested, the next step is to establish relationships between these dependency entities and the corresponding service entities.

1. Go to the Builder in your Port portal, select the Service blueprint, and click on New relation to create a relation between the service and dependency blueprints.

2. Click on the ... button in the top right corner of the Service blueprint and select Edit JSON.

3. Add this JSON to establish the relationship:

     "dependencies": {
       "title": "Dependencies",
       "target": "dependency",
       "required": false,
       "many": true
     }

4. Head back to the data sources page and add one of the following mapping approaches:

   Direct mapping

   The most straightforward way to set a relation's value is to explicitly specify the related entity's identifier:

     - kind: file
       selector:
         query: 'true'
         files:
           - path: '**/package.json'
             organization: my-org  # Optional if githubOrganization is set (required if not set)
             repos:
               - name: MyRepo
                 branch: main
       port:
         entity:
           mappings:
             identifier: .repository.name
             blueprint: '"service"'
             properties: {}
             relations:
               dependencies: >-
                 [.content.dependencies | to_entries | map( .key + "_" +
                 (.value |
                   gsub("\\^"; "caret_") |
                   gsub("~"; "tilde_") |
                   gsub(">="; "gte_") |
                   gsub("<="; "lte_") |
                   gsub(">"; "gt_") |
                   gsub("<"; "lt_") |
                   gsub("@"; "at_") |
                   gsub("\\*"; "star") |
                   gsub(" "; "_")
                 ) ) | .[]]

   Mapping details

   This would establish a relation between the service and dependency entities based on the dependencies listed in the package.json file.

   Search query

   You can also use a search query to dynamically match services with their dependencies based on package information.

   This approach is particularly useful when you don't know the entity's identifier, but you do know the value of one of its properties.

   Add the snippet below to your mapping configuration to match services with dependencies based on the first package in dependencies/devDependencies. You can adjust the rules to match your organization's needs:

   - kind: file
     selector:
       query: 'true'
     files:
       - path: '**/package.json'
         organization: my-org  # Optional if githubOrganization is set (required if not set)
         repos:
           - name: MyRepo
             branch: main
     port:
       entity:
         mappings:
           identifier: .repository.name
           blueprint: '"service"'
           properties: {}
           relations:
             dependencies:
               combinator: '"or"'
               rules:
                 - property: '"package_name"'
                   operator: '"="'
                   value: .content.dependencies | to_entries[0].key
                 - property: '"package_name"'
                   operator: '"="'
                   value: >-
                     (.content.devDependencies // {}) | to_entries[0].key //
                     null

5. After you add the mapping, click on the resync button and watch your repositories being mapped to their dependencies as shown below in this example:

   

Conclusion

By following these steps, you can effectively ingest dependencies from package.json files and relate them to the corresponding repository entities in Port 🎉.

More relevant guides and examples:

• Port's GitHub Ocean integration
• Self-service actions and workflows