The nx-monorepo package vends a NxMonorepoProject Projen construct that adds [NX](https://nx.dev/getting-started/intro) monorepo support and manages your yarn/npm/pnpm workspaces on your behalf. This construct enables polyglot builds (and inter language build dependencies), build caching, dependency visualization and much, much more.
The PDK itself uses the nx-monorepo project itself and is a good reference for seeing how a complex, polyglot monorepo can be set up.
> **BREAKING CHANGES** (pre-release)
>
> * v0.13.0: `WorkspaceConfig.nxConfig` type `NxConfig => Nx.WorkspaceConfig`, and `overrideProjectTargets` removed in favor of `PDKProject.nx` config to manage Nx project configurations. See [PR 231](https://github.com/aws/aws-prototyping-sdk/pull/231).
To get started simply run the following command in an empty directory:
```bash
npx projen new --from @aws-prototyping-sdk/nx-monorepo
```
This will bootstrap a new Projen monorepo and contain the following in the .projenrc.ts:
```python
import { nx_monorepo } from "aws-prototyping-sdk";
const project = new nx_monorepo.NxMonorepoProject({
defaultReleaseBranch: "main",
deps: ["aws-cdk-lib", "constructs", "cdk-nag"],
devDeps: ["aws-prototyping-sdk"],
name: "my-package",
});
project.synth();
```
To add new packages to the monorepo, you can simply add them as a child to the monorepo. To demonstrate, lets add a PDK Pipeline TS Project as a child as follows:
```python
import { nx_monorepo } from "aws-prototyping-sdk";
const project = new nx_monorepo.NxMonorepoProject({
defaultReleaseBranch: "main",
deps: ["aws-cdk-lib", "constructs", "cdk-nag"],
devDeps: ["aws-prototyping-sdk"],
name: "my-package",
});
new PDKPipelineTsProject({
parent: project,
outdir: "packages/cicd",
defaultReleaseBranch: "mainline",
name: "cicd",
cdkVersion: "2.1.0"
});
project.synth();
```
Once added, run `npx projen` from the root directory. You will now notice a new TS package has been created under the packages/cicd path.
Now let's add a python project to the monorepo and add an inter-language build dependency.
```python
import { nx_monorepo } from "aws-prototyping-sdk";
import { PDKPipelineTsProject } from "aws-prototyping-sdk/pipeline";
import { PythonProject } from "projen/lib/python";
const project = new nx_monorepo.NxMonorepoProject({
defaultReleaseBranch: "main",
deps: ["aws-cdk-lib", "constructs", "cdk-nag"],
devDeps: ["aws-prototyping-sdk"],
name: "test",
});
const pipelineProject = new PDKPipelineTsProject({
parent: project,
outdir: "packages/cicd",
defaultReleaseBranch: "mainline",
name: "cicd",
cdkVersion: "2.1.0"
});
// Standard Projen projects also work here
const pythonlib = new PythonProject({
parent: project,
outdir: "packages/pythonlib",
authorEmail: "",
authorName: "",
moduleName: "pythonlib",
name: "pythonlib",
version: "0.0.0"
});
// Pipeline project depends on pythonlib to build first
project.addImplicitDependency(pipelineProject, pythonlib);
project.synth();
```
Run `npx projen` from the root directory. You will now notice a new Python package has been created under packages/pythonlib.
To visualize our dependency graph, run the following command from the root directory: `npx nx graph`.
Now lets test building our project, from the root directory run `npx nx run-many --target=build --nx-bail`. As you can see, the pythonlib was built first followed by the cicd package.
> This is equivalent to running `yarn build`, `pnpm build`, or `npm run build` depending on your node package manager, and similarly `yarn build` also accepts the same [Nx Run-Many options](https://nx.dev/packages/nx/documents/run-many#options) (eg: `yarn build --projects=cicd`).
The NxMonorepoProject also manages your yarn/pnpm workspaces for you and synthesizes these into your package.json pnpm-workspace.yml respectively.
For more information on NX commands, refer to this [documentation](https://nx.dev/using-nx/nx-cli).
### Homogenous Dependencies
As well as adding implicit dependencies, you can add dependencies between projects of the same language in order to have one project consume another project's code.
#### Typescript
Since the `NxMonorepoProject` manages a yarn/npm/pnpm workspace, configuring dependencies between Typescript projects is as straightforward as referencing them in `deps`.
Note that dependencies cannot be added in the same project synthesis (`npx projen`) as when projects are created. This means a two-pass approach is recommended, first to create your new projects, and then to add the dependencies.
For example:
First add your new projects:
```python
new TypeScriptProject({
parent: monorepo,
outdir: "packages/a",
defaultReleaseBranch: "main",
name: "project-a"
});
new TypeScriptProject({
parent: monorepo,
outdir: "packages/b",
defaultReleaseBranch: "main",
name: "project-b",
});
```
Synthesise, then you can set up your dependency:
```python
const a = new TypeScriptProject({
parent: monorepo,
outdir: "packages/a",
defaultReleaseBranch: "main",
name: "project-a"
});
new TypeScriptProject({
parent: monorepo,
outdir: "packages/b",
defaultReleaseBranch: "main",
name: "project-b",
// B depends on A
deps: [a.package.packageName],
});
```
#### Python
##### Poetry (Recommended)
The recommended way to configure dependencies between python projects within your monorepo is to use Poetry. Poetry sets up separate virtual environments per project but also supports local file dependencies. You can use the monorepo's `addPythonPoetryDependency` method:
```python
const a = new PythonProject({
parent: monorepo,
outdir: 'packages/a',
moduleName: 'a',
name: 'a',
authorName: 'jack',
authorEmail: 'me@example.com',
version: '1.0.0',
poetry: true,
});
const b = new PythonProject({
parent: monorepo,
outdir: 'packages/b',
moduleName: 'b',
name: 'b',
authorName: 'jack',
authorEmail: 'me@example.com',
version: '1.0.0',
poetry: true,
});
// b depends on a
monorepo.addPythonPoetryDependency(b, a);
```
##### Pip
If you are using pip for your python projects, you can set up a dependency using a single shared virtual environment. You can then install packages you wish to depend on into that environment using pip's [Editable Installs](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs).
You will also need to add an implicit dependency to tell the monorepo the correct build order for your packages.
For example:
```python
const sharedEnv: VenvOptions = {
envdir: '../../.env',
};
const a = new PythonProject({
parent: monorepo,
outdir: 'packages/a',
moduleName: 'a',
name: 'a',
authorName: 'jack',
authorEmail: 'me@example.com',
version: '1.0.0',
venvOptions: sharedEnv,
});
// Install A into the virtual env since it is consumed by B
a.tasks.tryFind('install')!.exec('pip install --editable .');
const b = new PythonProject({
parent: monorepo,
outdir: 'packages/b',
moduleName: 'b',
name: 'b',
authorName: 'jack',
authorEmail: 'me@example.com',
version: '1.0.0',
venvOptions: sharedEnv,
// B depends on A
deps: [a.moduleName],
});
// Add the implicit dependency so that the monorepo will build A before B
monorepo.addImplicitDependency(b, a);
```
#### Java
The recommended way to configure dependencies between java projects within your monorepo is to use shared maven repositories. The default java project build will already create a distributable in the correct format for a maven repository in its `dist/java` folder, so you can use this as a repository. You can use the monorepo's `addJavaDependency` method:
For example:
```python
const a = new JavaProject({
parent: monorepo,
outdir: 'packages/a',
groupId: 'com.mycompany',
artifactId: 'a',
name: 'a',
version: '1.0.0',
});
const b = new JavaProject({
parent: monorepo,
outdir: 'packages/b',
groupId: 'com.mycompany',
artifactId: 'b',
name: 'b',
version: '1.0.0',
});
// b depends on a
monorepo.addJavaDependency(b, a);
```
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-prototyping-sdk",
"name": "aws-prototyping-sdk.nx-monorepo",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.7",
"maintainer_email": "",
"keywords": "",
"author": "AWS APJ COPE<apj-cope@amazon.com>",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/f2/fb/3f6dfee57799321c9653752b41253d2f396292543e3e2624c1fbce1b5ead/aws_prototyping_sdk.nx_monorepo-0.19.68.tar.gz",
"platform": null,
"description": "The nx-monorepo package vends a NxMonorepoProject Projen construct that adds [NX](https://nx.dev/getting-started/intro) monorepo support and manages your yarn/npm/pnpm workspaces on your behalf. This construct enables polyglot builds (and inter language build dependencies), build caching, dependency visualization and much, much more.\n\nThe PDK itself uses the nx-monorepo project itself and is a good reference for seeing how a complex, polyglot monorepo can be set up.\n\n> **BREAKING CHANGES** (pre-release)\n>\n> * v0.13.0: `WorkspaceConfig.nxConfig` type `NxConfig => Nx.WorkspaceConfig`, and `overrideProjectTargets` removed in favor of `PDKProject.nx` config to manage Nx project configurations. See [PR 231](https://github.com/aws/aws-prototyping-sdk/pull/231).\n\nTo get started simply run the following command in an empty directory:\n\n```bash\nnpx projen new --from @aws-prototyping-sdk/nx-monorepo\n```\n\nThis will bootstrap a new Projen monorepo and contain the following in the .projenrc.ts:\n\n```python\nimport { nx_monorepo } from \"aws-prototyping-sdk\";\n\nconst project = new nx_monorepo.NxMonorepoProject({\n defaultReleaseBranch: \"main\",\n deps: [\"aws-cdk-lib\", \"constructs\", \"cdk-nag\"],\n devDeps: [\"aws-prototyping-sdk\"],\n name: \"my-package\",\n});\n\nproject.synth();\n```\n\nTo add new packages to the monorepo, you can simply add them as a child to the monorepo. To demonstrate, lets add a PDK Pipeline TS Project as a child as follows:\n\n```python\nimport { nx_monorepo } from \"aws-prototyping-sdk\";\n\nconst project = new nx_monorepo.NxMonorepoProject({\n defaultReleaseBranch: \"main\",\n deps: [\"aws-cdk-lib\", \"constructs\", \"cdk-nag\"],\n devDeps: [\"aws-prototyping-sdk\"],\n name: \"my-package\",\n});\n\nnew PDKPipelineTsProject({\n parent: project,\n outdir: \"packages/cicd\",\n defaultReleaseBranch: \"mainline\",\n name: \"cicd\",\n cdkVersion: \"2.1.0\"\n});\n\nproject.synth();\n```\n\nOnce added, run `npx projen` from the root directory. You will now notice a new TS package has been created under the packages/cicd path.\n\nNow let's add a python project to the monorepo and add an inter-language build dependency.\n\n```python\nimport { nx_monorepo } from \"aws-prototyping-sdk\";\nimport { PDKPipelineTsProject } from \"aws-prototyping-sdk/pipeline\";\nimport { PythonProject } from \"projen/lib/python\";\n\nconst project = new nx_monorepo.NxMonorepoProject({\n defaultReleaseBranch: \"main\",\n deps: [\"aws-cdk-lib\", \"constructs\", \"cdk-nag\"],\n devDeps: [\"aws-prototyping-sdk\"],\n name: \"test\",\n});\n\nconst pipelineProject = new PDKPipelineTsProject({\n parent: project,\n outdir: \"packages/cicd\",\n defaultReleaseBranch: \"mainline\",\n name: \"cicd\",\n cdkVersion: \"2.1.0\"\n});\n\n// Standard Projen projects also work here\nconst pythonlib = new PythonProject({\n parent: project,\n outdir: \"packages/pythonlib\",\n authorEmail: \"\",\n authorName: \"\",\n moduleName: \"pythonlib\",\n name: \"pythonlib\",\n version: \"0.0.0\"\n});\n\n// Pipeline project depends on pythonlib to build first\nproject.addImplicitDependency(pipelineProject, pythonlib);\n\nproject.synth();\n```\n\nRun `npx projen` from the root directory. You will now notice a new Python package has been created under packages/pythonlib.\n\nTo visualize our dependency graph, run the following command from the root directory: `npx nx graph`.\n\nNow lets test building our project, from the root directory run `npx nx run-many --target=build --nx-bail`. As you can see, the pythonlib was built first followed by the cicd package.\n\n> This is equivalent to running `yarn build`, `pnpm build`, or `npm run build` depending on your node package manager, and similarly `yarn build` also accepts the same [Nx Run-Many options](https://nx.dev/packages/nx/documents/run-many#options) (eg: `yarn build --projects=cicd`).\n\nThe NxMonorepoProject also manages your yarn/pnpm workspaces for you and synthesizes these into your package.json pnpm-workspace.yml respectively.\n\nFor more information on NX commands, refer to this [documentation](https://nx.dev/using-nx/nx-cli).\n\n### Homogenous Dependencies\n\nAs well as adding implicit dependencies, you can add dependencies between projects of the same language in order to have one project consume another project's code.\n\n#### Typescript\n\nSince the `NxMonorepoProject` manages a yarn/npm/pnpm workspace, configuring dependencies between Typescript projects is as straightforward as referencing them in `deps`.\n\nNote that dependencies cannot be added in the same project synthesis (`npx projen`) as when projects are created. This means a two-pass approach is recommended, first to create your new projects, and then to add the dependencies.\n\nFor example:\n\nFirst add your new projects:\n\n```python\nnew TypeScriptProject({\n parent: monorepo,\n outdir: \"packages/a\",\n defaultReleaseBranch: \"main\",\n name: \"project-a\"\n});\n\nnew TypeScriptProject({\n parent: monorepo,\n outdir: \"packages/b\",\n defaultReleaseBranch: \"main\",\n name: \"project-b\",\n});\n```\n\nSynthesise, then you can set up your dependency:\n\n```python\nconst a = new TypeScriptProject({\n parent: monorepo,\n outdir: \"packages/a\",\n defaultReleaseBranch: \"main\",\n name: \"project-a\"\n});\n\nnew TypeScriptProject({\n parent: monorepo,\n outdir: \"packages/b\",\n defaultReleaseBranch: \"main\",\n name: \"project-b\",\n // B depends on A\n deps: [a.package.packageName],\n});\n```\n\n#### Python\n\n##### Poetry (Recommended)\n\nThe recommended way to configure dependencies between python projects within your monorepo is to use Poetry. Poetry sets up separate virtual environments per project but also supports local file dependencies. You can use the monorepo's `addPythonPoetryDependency` method:\n\n```python\nconst a = new PythonProject({\n parent: monorepo,\n outdir: 'packages/a',\n moduleName: 'a',\n name: 'a',\n authorName: 'jack',\n authorEmail: 'me@example.com',\n version: '1.0.0',\n poetry: true,\n});\n\nconst b = new PythonProject({\n parent: monorepo,\n outdir: 'packages/b',\n moduleName: 'b',\n name: 'b',\n authorName: 'jack',\n authorEmail: 'me@example.com',\n version: '1.0.0',\n poetry: true,\n});\n\n// b depends on a\nmonorepo.addPythonPoetryDependency(b, a);\n```\n\n##### Pip\n\nIf you are using pip for your python projects, you can set up a dependency using a single shared virtual environment. You can then install packages you wish to depend on into that environment using pip's [Editable Installs](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs).\n\nYou will also need to add an implicit dependency to tell the monorepo the correct build order for your packages.\n\nFor example:\n\n```python\nconst sharedEnv: VenvOptions = {\n envdir: '../../.env',\n};\n\nconst a = new PythonProject({\n parent: monorepo,\n outdir: 'packages/a',\n moduleName: 'a',\n name: 'a',\n authorName: 'jack',\n authorEmail: 'me@example.com',\n version: '1.0.0',\n venvOptions: sharedEnv,\n});\n\n// Install A into the virtual env since it is consumed by B\na.tasks.tryFind('install')!.exec('pip install --editable .');\n\nconst b = new PythonProject({\n parent: monorepo,\n outdir: 'packages/b',\n moduleName: 'b',\n name: 'b',\n authorName: 'jack',\n authorEmail: 'me@example.com',\n version: '1.0.0',\n venvOptions: sharedEnv,\n // B depends on A\n deps: [a.moduleName],\n});\n\n// Add the implicit dependency so that the monorepo will build A before B\nmonorepo.addImplicitDependency(b, a);\n```\n\n#### Java\n\nThe recommended way to configure dependencies between java projects within your monorepo is to use shared maven repositories. The default java project build will already create a distributable in the correct format for a maven repository in its `dist/java` folder, so you can use this as a repository. You can use the monorepo's `addJavaDependency` method:\n\nFor example:\n\n```python\nconst a = new JavaProject({\n parent: monorepo,\n outdir: 'packages/a',\n groupId: 'com.mycompany',\n artifactId: 'a',\n name: 'a',\n version: '1.0.0',\n});\n\nconst b = new JavaProject({\n parent: monorepo,\n outdir: 'packages/b',\n groupId: 'com.mycompany',\n artifactId: 'b',\n name: 'b',\n version: '1.0.0',\n});\n\n// b depends on a\nmonorepo.addJavaDependency(b, a);\n```\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "@aws-prototyping-sdk/nx-monorepo",
"version": "0.19.68",
"project_urls": {
"Homepage": "https://github.com/aws/aws-prototyping-sdk",
"Source": "https://github.com/aws/aws-prototyping-sdk"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "40409f9e0317f35b3d22c236aa77270b4d60fc5615b5ffc097c6e883fe8caa9f",
"md5": "38d25337531461362598d8f4bdd521bf",
"sha256": "4859d5f10ac048a43c1d73c17aa43cf58c076200d23fe70355e0d7b1c106dd3c"
},
"downloads": -1,
"filename": "aws_prototyping_sdk.nx_monorepo-0.19.68-py3-none-any.whl",
"has_sig": false,
"md5_digest": "38d25337531461362598d8f4bdd521bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.7",
"size": 1147137,
"upload_time": "2023-08-24T23:16:55",
"upload_time_iso_8601": "2023-08-24T23:16:55.955455Z",
"url": "https://files.pythonhosted.org/packages/40/40/9f9e0317f35b3d22c236aa77270b4d60fc5615b5ffc097c6e883fe8caa9f/aws_prototyping_sdk.nx_monorepo-0.19.68-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2fb3f6dfee57799321c9653752b41253d2f396292543e3e2624c1fbce1b5ead",
"md5": "b7f9be1bd5e0a6e412559e48c6abcb24",
"sha256": "a25800bee81322691644cf6ecb077acd398e673adbf12c460554037e17783d1f"
},
"downloads": -1,
"filename": "aws_prototyping_sdk.nx_monorepo-0.19.68.tar.gz",
"has_sig": false,
"md5_digest": "b7f9be1bd5e0a6e412559e48c6abcb24",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.7",
"size": 1147604,
"upload_time": "2023-08-24T23:16:57",
"upload_time_iso_8601": "2023-08-24T23:16:57.822810Z",
"url": "https://files.pythonhosted.org/packages/f2/fb/3f6dfee57799321c9653752b41253d2f396292543e3e2624c1fbce1b5ead/aws_prototyping_sdk.nx_monorepo-0.19.68.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-24 23:16:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-prototyping-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-prototyping-sdk.nx-monorepo"
}
JSON
