From 894c8fe30d461c7cb630320e75c31be19ac81bc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Niccol=C3=B2=20Belli?= Date: Wed, 6 Dec 2023 16:28:03 +0100 Subject: [PATCH] Misc corrections Co-authored-by: Aleksandra --- website/pages/blog/accounts.js-1.0-rc.mdx | 66 +++++++++++------------ 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/website/pages/blog/accounts.js-1.0-rc.mdx b/website/pages/blog/accounts.js-1.0-rc.mdx index a6f6c1a7b..2a0868a7f 100644 --- a/website/pages/blog/accounts.js-1.0-rc.mdx +++ b/website/pages/blog/accounts.js-1.0-rc.mdx @@ -9,31 +9,31 @@ image: /blog-assets/accounts.js-1.0-rc/accounts-logo-wide.png thumbnail: /blog-assets/accounts.js-1.0-rc/accounts-logo-squared.png --- -The first release candidate of [Accounts.js](https://www.accountsjs.com/) 1.0 has finally been released! +The first release candidate of [Accounts.js](https://www.accountsjs.com/) 1.0 is now officially available! -This is the culmination of a long process of rearchitecting the whole framework, which is finally a first class [graphql-modules](https://the-guild.dev/graphql/modules) citizen and supports latest graphql 16 and [graphql-tools](https://the-guild.dev/graphql/tools) 10 as well as any modern GraphQL server including Apollo Server 4 and [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) 5. +It's the culmination of a long process of rearchitecting the whole framework, which is finally a first-class citizen of the [graphql-modules](https://the-guild.dev/graphql/modules) package. It supports the latest GraphQL.js v16 and [graphql-tools](https://the-guild.dev/graphql/tools) v10 as well as any modern GraphQL server including Apollo Server v4 and [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server) v5. ## What Is Accounts.js -The `@accounts` suite of packages aims to provide an end to end authentication and accounts management solution, with a simple way to start while preserving options for configuration. These packages provide OAuth support for popular providers such as Instagram or Twitter, two factor authentication, password based accounts along with recovery options and customizable account creation and validation. +The `@accounts` suite of packages aims to provide an end-to-end authentication and accounts management solution with n user-friendly way to start while preserving options for configuration. These packages offer OAuth support for popular providers such as Instagram or Twitter, two-factor authentication, password-based accounts, recovery options, and customizable account creation and validation. -Three pieces need to be configured to use accounts-js in your application: +To integrate `accounts-js` into your application, you need to configure these three components: 1. **Transports**: - Since accounts-js is very flexible, it can be used with multiple transports. For now we provide packages for both GraphQL and REST. + The flexibility of `accounts-js` allows it to be integrated with different types of APIs. For now, we provide packages for both GraphQL and REST. 2. **Databases**: - We provide a native mongo integration. We also have MikroORM and Typeorm integrations which will let you use accounts-js with any kind of databases. Optionally Redis can be used to store the sessions and you can also provide any custom database adapter that will work with existing authentication strategies by simply implementing the `DatabaseInterface`. + Accounts.js provides a [native Mongo integration](https://github.com/accounts-js/accounts/tree/master/packages/database-mongo). Additionally, it offers [MikroORM](https://github.com/accounts-js/accounts/tree/master/packages/database-mikro-orm) and [Typeorm](https://github.com/accounts-js/accounts/tree/master/packages/database-typeorm) integrations, which lets you use `accounts-js` with any database. Optionally, you can use Redis to store the session data, or provide a custom database adapter that will work with existing authentication strategies by implementing the `DatabaseInterface`. 3. **Strategies**: - You can use multiple strategies to let your users access to your app. For now we support authentication via the email/username and password combination, magic link and oauth. + You can use multiple strategies to let your users access your app. For now, it supports password-based, magic link, and OAuth authentication methods. -**TIP**: Accounts.js is a **full stack** solution, so in addition it also provides a full set of packages to seamlessly implement your chosen authentication workflow in your **client** as well! +**Note**: Accounts.js is a **full-stack** solution, providing a full set of packages to seamlessly implement your chosen authentication workflow on the **client** as well! ## The New Architecture -In Accounts.js 1.0 we use graphql-modules to compose the authentication framework, automatically piecing together your preferred database adapter(s) with the authentication service(s) of your choice (password, oauth, etc). -We support both GraphQL and REST transports: for the former graphql-modules will automatically provide you the schema based on the modules that you're using while for the latter it will simply provide dependency injection across the various modules to piece them together. +In Accounts.js 1.0, we use `graphql-modules` to compose the authentication framework, automatically piecing together your preferred database adapter(s) with the authentication service(s) of your choice (password-based, OAuth, etc). +As mentioned before, `accounts-js` currently supports GraphQL and REST. For the former, `graphql-modules` automatically provides the schema based on the modules you're using, while for the latter, it provides dependency injection across the various modules to piece them together. ```ts const app = createApplication({ @@ -48,7 +48,7 @@ const app = createApplication({ schemaBuilder: buildSchema({ typeDefs, resolvers }), ``` -If your application already makes use of graphql-modules all you need to do is adding the accounts.js modules of choice to your own, otherwise it's only a matter of providing your resolvers and type definitions to the `buildSchema` function. +If your application already uses `graphql-modules`, all you need to do is add the `accounts.js` modules of your choice to your own application module. Otherwise, it's a matter of providing your resolvers and type definitions to the `buildSchema` function. ```ts // GraphQL Yoga 5 @@ -67,11 +67,11 @@ startStandaloneServer(apollo, { }); ``` -At this point whatever is your GraphQL server of choice your authenticated application is just a few lines of code away. +At this point, whatever your GraphQL server of choice, your authenticated application is just a few lines of code away. > But what if all I care is REST? -Use the graphql-modules injector to retrieve the `AccountsServer` instance and feed it to `@accounts/rest-express`! +Use the `graphql-modules` injector to retrieve the `AccountsServer` instance and feed it to `@accounts/rest-express`! ```ts const controller = app.createOperationController({ @@ -81,12 +81,12 @@ const accountsServer = controller.injector.get(AccountsServer); expressApp.use(accountsExpress(accountsServer)); ``` -Alternatively if you don't want to use graphql-modules at all you can still manually instantiate the providers (there is an example in the [examples folder](https://github.com/accounts-js/accounts/tree/master/examples) if you are interested). +Alternatively, if you don't want to use `graphql-modules`, you can still manually instantiate the providers. Here's [an example](https://github.com/accounts-js/accounts/blob/master/examples/rest-express-typescript-without-modules/src/index.ts). ## The New MikroORM Database Adapter -The second big change of Accounts.js 1.0 is the release of the brand new [MikroORM](https://mikro-orm.io/) database adapter. MikroORM is a TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. It is also very well written and actively developed. -Today also marks the release of the v6 of MikroORM, which incorporates [my recent work](https://github.com/mikro-orm/mikro-orm/pull/4321) to automatically batch references and collections and retrieve them via dataloaders firing a single query. This is especially useful with the GraphQL transport since it automatically solves its notorious N+1 problem without you even noticing it. More informations [here](https://mikro-orm.io/docs/dataloaders). +The second big change in Accounts.js 1.0 is the release of the brand new [MikroORM](https://mikro-orm.io/) database adapter. MikroORM is a TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. It is also very well-written and actively developed. +Today also marks the release of the v6 of MikroORM, which incorporates [my recent work](https://github.com/mikro-orm/mikro-orm/pull/4321) to automatically batch references and collections and retrieve them via dataloaders firing a single query. This is especially useful with GraphQL transport since it automatically solves its notorious N+1 problem without you even noticing it—more information [here](https://mikro-orm.io/docs/dataloaders). ```ts @Entity() @@ -107,7 +107,7 @@ export class User extends AccountsUser { } ``` -The Accounts.js MikroORM database adapter can be backed by your database of choice (PostgreSQL, MySQL, MariaDB, SQLite, MongoDB) and won't force you into any existing entity schema: use the existing entities or provide your own, but make sure to extend the base ones so that authentication can occur. +The Accounts.js MikroORM database adapter can be backed by your database of choice (PostgreSQL, MySQL, MariaDB, SQLite, MongoDB). It won't force you into any existing entity schema: you can use the existing entities or provide your own, but please make sure to extend the base ones so that authentication can occur. ```ts entities: [ @@ -119,11 +119,11 @@ entities: [ ], ``` -Under the hood it makes use of MikroORM's [EntitySchema](https://mikro-orm.io/docs/entity-schema) so you will have to provide the schema for the base entities as well. +Under the hood, it uses MikroORM's [EntitySchema](https://mikro-orm.io/docs/entity-schema), so you must also provide the schema for the base entities. -## Breaking changes +## Breaking Changes -`@accounts/boost` has been removed. It was no longer deemed necessary because the new graphql-modules architecture already allows you to plug and play the various modules. For example instead of providing an existing database connection you can easily let `@accounts/module-mongo` create a new one for you: +`@accounts/boost` has been removed. It was no longer deemed necessary because of the new `graphql-modules` architecture that already allows you to plug and play various modules. For example, instead of providing an existing database connection, you can let `@accounts/module-mongo` create a new one for you: ```ts const app = createApplication({ @@ -143,9 +143,9 @@ const app = createApplication({ * `@accounts/module-password` * `@accounts/module-typeorm` -Use these packages to piece together your desired authentication workflow along with your preferred database adapter. Despite the big changes under the hood I strived to keep the public API mostly the same so migrating to 1.0 shouldn't be a huge effort. +These packages can assemble your desired authentication workflow and your preferred database adapter. Despite the significant changes under the hood, I strived to keep the public API mostly the same, so migrating to 1.0 should be a manageable effort. -## What's new +## What's New * We switched from pnpm to yarn 4. * We now return code 401 unmasked errors when unauthorized. @@ -192,26 +192,26 @@ Use these packages to piece together your desired authentication workflow along * Upgraded `@apollo/server` to 4.9 * Upgraded `docusaurus` to v3 -## What's left before 1.0 stable +## Remaining Work For The Stable Release -OAuth authentication, while working, surely deserves some love. While REST endpoints for OAuth should be functional there are no mutations nor resolvers yet, meaning that you can't use it with the GraphQL transport. I'd also like to go through the OAuth code and write some examples. `@accounts/oauth-instagram` in particular still relies upon the deprecated `request` package and should be updated. Other popular OAuth providers like Facebook still need to be added (but PRs exist). +OAuth authentication, while working, surely deserves some love. While REST endpoints for OAuth should be functional, there are no mutations or resolvers yet, meaning you can't use them with the GraphQL transport. I'd also like to review the OAuth code and write some examples. `@accounts/oauth-instagram`, in particular, still relies upon the deprecated `request` package and should be updated. Other popular OAuth providers like Facebook still need to be added (but PRs exist). -Before 1.0 stable gets released I plan to at least get the existing providers in a better shape, together with examples and the relevant GraphQL schema. +Before the 1.0 stable gets released, I plan to get the existing providers in a better shape, together with examples and the relevant GraphQL schema. ## Post 1.0 -I'd like to create a new `@accounts/phone` authentication service which lets you authenticate via SMS OTPs. That would be especially useful in react-native applications where you could automatically read the sms and automate the authentication process. +I want to create a new `@accounts/phone` authentication service which lets you authenticate via SMS OTPs. That would be especially useful in react-native applications where you could automatically read the SMS and automate the authentication process. -Currently Accounts.js bundles CommonJS code. While CommonJS can be imported in both CommonJS and ESM applications that would rule out Deno/Bun support. For the same reason we cannot use a wrapper either: while that would allow to use ESM imports it wouldn't be real ESM and thus won't be compatible. The remaning alternatives are pure ESM and dual packages. While several library authors opted for the former because of [dual package hazard](https://nodejs.org/api/packages.html#packages_dual_package_hazard) concerns I weight the benefits differently. While dual package hazards are real the whole GraphQL echosystem relies on dual packages thus using `instanceof` is already an hazard. These authors suggest to use `async imports` to import their pure ESM libraries in commonjs projects, which exposes everyone to the very same hazard (not even considering the fact that this is only viable in async contexts). That basically goes against the reason why they decided to bundle pure esm in the first place. I personally think that it's still too early to target pure esm and dual package is the lesser evil so I'm leaning towards that for future releases, but I'm ready to change my mind if you provide me enough arguments. +Currently, Accounts.js bundles CommonJS code. While CommonJS can be imported in both CommonJS and ESM applications, that would rule out Deno/Bun support. For the same reason, we cannot use a wrapper either: while that would allow us to use ESM imports, it wouldn't be real ESM and thus won't be compatible. The remaining alternatives are pure ESM and dual packages. While several library authors opted for the former because of [dual package hazard](https://nodejs.org/api/packages.html#packages_dual_package_hazard) concerns, I weigh the benefits differently. While dual package hazards are real, the whole GraphQL ecosystem relies on dual packages; thus, using `instance of` is already a hazard. These authors suggest using `async imports` to import their pure ESM libraries in common projects, which exposes everyone to the same hazard (not even considering that this is only viable in async contexts). That goes against why they decided to bundle pure ESM in the first place. I think it's still too early to target pure ESM, and dual package is the lesser evil, so I'm leaning towards that for future releases, but I'm ready to change my mind if you provide enough arguments. -I'd also like to implement some form of accounts linking, where users could link their existing account with a different authentication service (for example password and oauth). +I'd also like to implement some form of account linking, where users could link their existing account with a different authentication service (for example, password-based and OAuth). -I would like to a extend Multi Factor Authentication outside of the password service, baking it into the core of accounts.js so that any authentication service can take advantage of it. +I want to extend Multi-Factor Authentication outside of the password service, baking it into the core of accounts.js so that any authentication service can take advantage of it. -If future major versions of Accounts.js will introduce breaking changes to the database structure I would like to provide migrations directly via the `@accounts/mikro-orm` package. +If future major versions of Accounts.js introduce breaking changes to the database structure, I would like to provide migrations directly via the `@accounts/mikro-orm` package. -Last but not the least I would like to bake in cookies authentication. Not only that would fare better against XSS, it would also allow server side rendering and thus enable the usage of frameworks like Next.js. Alternative storage methods would remain available for those using native applications. +Last but not least, I would like to bake in cookies authentication. Not only would that fare better against XSS, but it would also allow server-side rendering and thus enable the usage of frameworks like Next.js. Alternative storage methods would remain available for those using native applications. -At the end of the day 1.0 is just a number and what I really want is to provide stable APIs via semantic versioning. +At the end of the day, 1.0 is just a number, and I really want to provide stable APIs via semantic versioning. -Accounts.js is an open source project and we welcome your [contributions](https://github.com/accounts-js/accounts)! +Accounts.js is an open-source project, and we welcome your [contributions](https://github.com/accounts-js/accounts)!