docs: rework Introduction (#1236)

Author: jbroma

website/src/latest/docs/getting-started/introduction.md

@@ -2,55 +2,47 @@
 
 Before diving deep into Re.Pack and introducing it into project, it's important to understand when and why to use Re.Pack and how does it compare with alternatives.
 
-## What Re.Pack actually is?
+## About Re.Pack
 
-React Native environment and Browser environment have differences. React Native needs to run additional JS setup/init code so that it's usable at all. There's a great discrepancy between available APIs. In React Native we also have platform specific files — e.g.: `.ios.js`, `.android.js` and so on.
+Re.Pack is a modern toolkit that wraps Rspack and webpack to make them work seamlessly with React Native applications.
 
-Putting all the above together, makes webpack **unable to produce bundle** at all due to build errors and then the **bundle produced by webpack is unusable** by default.
+The toolkit includes:
 
-Therefore, we need to make changes to webpack configuration and change how and what webpack puts into the final bundle. All these necessary changes are encapsulated inside Re.Pack in form of webpack plugins.
+- **React Native-specific plugins and loaders** that handle platform differences (platform specific files, assets, etc.)
+- **Integrated development server** with Hot Module Replacement (HMR) + React Refresh, and debugging capabilities through React Native Devtools
+- **Runtime modules** like ScriptManager for advanced features like code splitting and Module Federation
 
-So to answer the question:
-
-:::info Re.Pack is what makes webpack and webpack-produced bundle usable in React Native application.
-:::
-
-## Why & when
-
-The main feature of Re.Pack is webpack and its ecosystem of: loaders, plugins and support for various features like symlinks, aliases etc.
-
-However, because Re.Pack is based on webpack, **it is targeted towards advanced users who already know how to use webpack** and want to leverage webpack ecosystem.
-
-:::tip
+## Design goals
 
-If you're just starting with React Native, it's better to stick with the default solution — Metro, since you probably won't benefit much from switching to webpack and Re.Pack.
+Re.Pack is designed to be a **drop-in replacement for Metro** with the primary goal of making migration as easy as possible. The toolkit aims to:
 
-:::
+- Provide seamless integration with existing React Native projects
+- Maintain compatibility with Metro's expected behavior while offering enhanced capabilities
+- Minimize configuration changes needed during migration
+- Offer a smooth transition path from Metro to advanced bundling features
 
-## Design goals
+This approach ensures teams can adopt Re.Pack incrementally, starting with basic Metro replacement and gradually leveraging advanced features like Module Federation and custom webpack configurations as needed.
 
-1. Re.Pack was design for the advanced users, as such it exposes _low-level API_ in form of webpack plugins and utilities, meaning we only give you the tools you need to build React Native application, but the actual configuration and maintenance of said config is on your shoulders.
-2. To support wide variety of use cases and give you as much control as possible, Re.Pack is written to allow you to bundle and run development server directly from webpack CLI as well by using React Native CLI. While it's recommended to stick with React Native CLI, you can pick one you want to go with.
-3. Based on our experience with [Haul](https://github.com/callstack/haul), we shift as much responsibility onto you as possible, so that we can develop features, move at reasonable pace and reduce maintenance cost. Therefore, Re.Pack should be used by seasoned React Native developers with at least basic experience with webpack.
+## Why & when
 
-## Re.Pack vs Metro
+Re.Pack is particularly valuable in these scenarios:
 
-Both Metro and Re.Pack have different approaches for the similar problem — bundling JavaScript code for your React Native application.
+### 1. **Microfrontends with Module Federation**
+Re.Pack provides first-class support for Module Federation, enabling you to build microfrontend architectures where different teams can develop and deploy parts of your mobile app independently.
 
-The main distinction is that, Metro is custom-built solution and Re.Pack uses webpack. As a result there few differences that you should consider when deciding the solution to use:
+### 2. **Advanced Tree Shaking**
+Leverage state-of-the-art tree shaking capabilities that can significantly reduce bundle size by eliminating unused code more effectively than Metro, helping you save valuable bytes in your final application bundle.
 
-- Metro is slightly faster - it has less overhead compared to webpack. Metro trades configurability for performance, whereas with webpack it's the other way around.
-- Webpack configuration options and ecosystem allows for much greater control and support for advanced use-cases.
+### 3. **High Customizability**
+Access to the full Rspack/webpack ecosystem means extensive customization options through loaders, plugins, and advanced configuration. You can implement complex build requirements that aren't possible with Metro.
 
-## Re.Pack vs Haul
+### 4. **Build Performance**
+Rspack's Rust-based architecture provides significant performance improvements for large codebases, especially when combined with advanced caching strategies.
 
-Re.Pack is a direct successor to [Haul](https://github.com/callstack/haul). Therefore we took the experience we gained with Haul while making rather major changes in the approach:
+Re.Pack is designed for teams that need these advanced capabilities and have developers willing to familiarize themselves with alternative bundling tools.
 
-- Re.Pack has smaller footprint and allows for greater level of customization, since you have direct access to the webpack config.
-- Re.Pack supports Hot Module Replacement + React Refresh, whereas Haul does not.
-- Haul supports legacy implementation of multi-bundling (though it requires to alter React Native source code, so we don't recommend that), whereas Re.Pack supports [Code Splitting](/docs/features/code-splitting), including [Module Federation](/docs/features/module-federation).
-- Re.Pack delivers better Developer Experience by providing you with more meaningful logs, easier usage and more customizability.
+:::tip Don't drop Metro just yet!
 
-## Re.Pack vs `@callstack/nativepack`
+If you're just starting with React Native, consider sticking with Metro - the default bundler for React Native applications. Re.Pack shines when you have specific requirements that Metro cannot address but is not compatible with tools that assume Metro as a bundler present in the project setup.
 
-Re.Pack is a rebranded version of `@callstack/nativepack`, which was a temporary name to avoid infringing on webpack trademark. They are both the same projects.
+:::