Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update the root README #133

Merged
merged 2 commits into from
Mar 31, 2025
Merged

docs: update the root README #133

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f0794f
docs: update the root README
agdimech Mar 31, 2025
9baa2c7
Merge branch 'main' into docs/readme
agdimech Mar 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 100 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,118 @@
# nx-plugin-for-aws
<div align="center">
<h1>NX plugin for AWS - @aws/nx-plugin</h1>
<h3>Quickly bootstrap and build AWS projects easily</h3>
<a href="https://opensource.org/licenses/Apache-2.0">
<img
src="https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg"
alt="Apache 2.0 License"
/>
</a>
<a href="https://codecov.io/gh/awslabs/nx-plugin-for-aws">
<img src="https://codecov.io/gh/awslabs/nx-plugin-for-aws/graph/badge.svg?token=X27pgFfxuQ" />
</a>
<a href="https://gitpod.io/new/?workspaceClass=g1-large#https://github.com/awslabs/nx-plugin-for-aws">
<img
src="https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod"
alt="Gitpod ready-to-code"
/>
</a>
<a href="https://github.com/awslabs/nx-plugin-for-aws/actions/workflows/ci.yml">
<img
src="https://github.com/awslabs/nx-plugin-for-aws/actions/workflows/ci.yml/badge.svg"
alt="Release badge"
/>
</a>
<a href="https://github.com/awslabs/nx-plugin-for-aws/commits/main">
<img
src="https://img.shields.io/github/commit-activity/w/awslabs/nx-plugin-for-aws"
alt="Commit activity"
/>
</a>
<br />
<br />
<figure>
<img src="docs/src/content/docs/assets/website-generator.gif" alt="Demo" />
</figure>
👉 See full documentation on <a href="https://awslabs.github.io/nx-plugin-for-aws">https://awslabs.github.io/nx-plugin-for-aws</a> 👈
</div>

<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg" alt="Apache 2.0 License"/></a>
<a href="https://codecov.io/gh/awslabs/nx-plugin-for-aws" ><img src="https://codecov.io/gh/awslabs/nx-plugin-for-aws/graph/badge.svg?token=X27pgFfxuQ"/></a>
<a href="https://gitpod.io/new/?workspaceClass=g1-large#https://github.com/awslabs/nx-plugin-for-aws"><img src="https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod" alt="Gitpod ready-to-code"/></a>
<a href="https://github.com/awslabs/nx-plugin-for-aws/actions/workflows/ci.yml"><img src="https://github.com/awslabs/nx-plugin-for-aws/actions/workflows/ci.yml/badge.svg" alt="Release badge"/></a>
<a href="https://github.com/awslabs/nx-plugin-for-aws/commits/main"><img src="https://img.shields.io/github/commit-activity/w/awslabs/nx-plugin-for-aws" alt="Commit activity"/></a>
## Intro

## Integrate with editors
[@aws/nx-plugin](https://github.com/awslabs/nx-plugin-for-aws) is a collection of generators to help you build cloud-native applications with AWS.

Enhance your Nx experience by installing [Nx Console](https://nx.dev/nx-console) for your favorite editor. Nx Console
provides an interactive UI to view your projects, run tasks, generate code, and more! Available for VSCode, IntelliJ and
comes with a LSP for Vim users.
## Key Features

## Build
- **Declarative**: Generate code that follows best practices for AWS cloud development.
- **Component-Based**: Add components to your project as needed, from React websites to serverless APIs using either the CLI or UI.
- **Learn Once, Use Anywhere**: Consistent patterns across different AWS services and application types.
- **Open for modification**: All code generated is your code and can be edited as you see fit.
- **Type safety**: Type-safety is employed to support IDE completions and reduce the number of runtime errors encountered.
- **Minimal dependencies**: Getting up and running is simple and only requires langugage level global dependencies.

```
pnpm nx run-many --target build --all
```
## Available Generators

## Docs
- `ts#project` - Generate a new TypeScript library.
- `ts#infra` - Generate a Typescript AWS CDK infrastructure project for your application.
- `ts#cloudscape-website` - Generate a new Cloudscape/React/Vite based web application.
- `ts#cloudscape-website#auth` - Add AWS Cognito authentication to your Cloudscape website.
- `ts#trpc-api` - Generate a tRPC backend service with Amazon API Gateway/AWS Lambda integration and [AWS Powertools](https://github.com/aws-powertools/powertools-lambda-typescript) pre-configured.
- `py#project` - Generate a uv based Python project.
- `py#fast-api` - Generate a FastAPI backend service with [AWS Powertools](https://github.com/aws-powertools/powertools-lambda-python) pre-configured.
- `api-connection` - Connect frontend applications to backend APIs.
- `license` - Automatically manage LICENSE files and source code headers in your workspace.

Run the local docs site with:
## Getting started

```
pnpm nx serve docs
@aws/nx-plugin has been designed for gradual adoption from the start, and **you can use as little or as much of it as you need**.

1. Create a new NX workspace

```bash
npx create-nx-workspace@~20.6.3 demo --pm=pnpm --preset=ts --ci=skip --formatter=prettier
cd demo
```

## Examples
2. Install the `@aws/nx-plugin`

```bash
pnpm add -Dw @aws/nx-plugin
```
pnpm nx generate @aws/nx-plugin:ts#infra infra --name=infra --directory=lib

3. Add components:

```bash
# Generate a tRPC API backend
pnpm nx g @aws/nx-plugin:ts#trpc-api

# Generate a Cloudscape website
pnpm nx g @aws/nx-plugin:ts#cloudscape-website

# Connect the frontend to the backend
pnpm nx g @aws/nx-plugin:api-connection

# Add authentication to your website
pnpm nx g @aws/nx-plugin:ts#cloudscape-website#auth

# Generate AWS CDK infrastructure
pnpm nx g @aws/nx-plugin:ts#infra
```

## Security
### Additional resources

- Use [Quick Start](https://awslabs.github.io/nx-plugin-for-aws/get_started/quick-start/) to get a taste of @aws/nx-plugin.
- [Build a Dungeon Adventure Game](https://awslabs.github.io/nx-plugin-for-aws/get_started/tutorials/dungeon-game/overview/) to get an in-depth guided tutorial on how to use the @aws/nx-plugin.
- [Add @aws/nx-plugin to your existing project](https://awslabs.github.io/nx-plugin-for-aws/get_started/tutorials/existing-project/)

## Contributing

The main purpose of this repository is to continue evolving @aws/nx-plugin, making it faster and easier to use. Development happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements.

Read our [Contributing Guide](CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to @aws/nx-plugin.

## Code of Conduct

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
This project has adopted a Code of Conduct that we expect project participants to adhere to. Please read the [Code of Conduct](CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.

## License

This project is licensed under the Apache-2.0 License.
@aws/nx-plugin is [Apache 2.0 licensed](LICENSE).
Loading